hangwin--mcp-chrome
hangerye
551 行
9.5 KiB
Markdown
551 行
9.5 KiB
Markdown
# 故障排除指南 🔧
|
||
|
||
Chrome MCP Server 的常见问题和解决方案。
|
||
|
||
## 📋 目录
|
||
|
||
- [安装问题](#安装问题)
|
||
- [Chrome 扩展问题](#chrome-扩展问题)
|
||
- [原生服务器问题](#原生服务器问题)
|
||
- [MCP 协议问题](#mcp-协议问题)
|
||
- [AI/SIMD 问题](#aisimd-问题)
|
||
- [性能问题](#性能问题)
|
||
- [网络捕获问题](#网络捕获问题)
|
||
|
||
## 🚀 安装问题
|
||
|
||
### Node.js 版本兼容性
|
||
|
||
**问题**：构建失败，出现 Node.js 版本错误
|
||
|
||
```
|
||
Error: Unsupported Node.js version
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 检查 Node.js 版本
|
||
node --version
|
||
|
||
# 如需要，安装 Node.js 18+
|
||
# 使用 nvm（推荐）
|
||
nvm install 18
|
||
nvm use 18
|
||
|
||
# 或从 nodejs.org 下载
|
||
```
|
||
|
||
### pnpm 安装问题
|
||
|
||
**问题**：找不到 `pnpm` 命令
|
||
|
||
```
|
||
bash: pnpm: command not found
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 全局安装 pnpm
|
||
npm install -g pnpm
|
||
|
||
# 或使用 corepack（Node.js 16.10+）
|
||
corepack enable
|
||
corepack prepare pnpm@latest --activate
|
||
```
|
||
|
||
### 构建失败
|
||
|
||
**问题**：`pnpm build` 期间构建失败
|
||
|
||
```
|
||
Error: Build failed with exit code 1
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 清理并重新构建
|
||
pnpm clean
|
||
pnpm install
|
||
pnpm build
|
||
|
||
# 检查特定包问题
|
||
pnpm build:shared
|
||
pnpm build:wasm
|
||
pnpm build:native
|
||
pnpm build:extension
|
||
```
|
||
|
||
## 🔌 Chrome 扩展问题
|
||
|
||
### 扩展无法加载
|
||
|
||
**问题**：扩展在 Chrome 中加载失败
|
||
|
||
**症状**：
|
||
|
||
- "清单文件丢失或不可读"
|
||
- "无效清单"
|
||
- 扩展显示为灰色
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查构建输出**：
|
||
|
||
```bash
|
||
cd app/chrome-extension
|
||
pnpm build
|
||
# 验证 dist/ 目录存在且包含 manifest.json
|
||
```
|
||
|
||
2. **验证 manifest.json**：
|
||
|
||
```bash
|
||
cat app/chrome-extension/dist/manifest.json
|
||
# 应包含有效的 JSON 和版本 3
|
||
```
|
||
|
||
3. **启用开发者模式**：
|
||
- 转到 `chrome://extensions/`
|
||
- 打开"开发者模式"
|
||
- 点击"加载已解压的扩展程序"
|
||
- 选择 `app/chrome-extension/dist`
|
||
|
||
### 原生消息连接失败
|
||
|
||
**问题**：扩展无法连接到原生服务器
|
||
|
||
```
|
||
Error: Native host has exited
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查原生服务器安装**：
|
||
|
||
```bash
|
||
# 验证全局安装
|
||
npm list -g mcp-chrome-bridge
|
||
|
||
# 如需要，重新安装
|
||
cd app/native-server
|
||
npm install -g .
|
||
```
|
||
|
||
2. **验证原生消息清单**：
|
||
|
||
```bash
|
||
# macOS
|
||
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.chromemcp.nativehost.json
|
||
|
||
# Linux
|
||
cat ~/.config/google-chrome/NativeMessagingHosts/com.chromemcp.nativehost.json
|
||
|
||
# Windows
|
||
# 检查注册表：HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.chromemcp.nativehost
|
||
```
|
||
|
||
3. **检查权限**：
|
||
|
||
```bash
|
||
# 确保可执行权限
|
||
chmod +x /path/to/mcp-chrome-bridge
|
||
```
|
||
|
||
### 扩展权限被拒绝
|
||
|
||
**问题**：扩展缺少必要权限
|
||
|
||
**解决方案**：
|
||
|
||
1. **手动授予权限**：
|
||
|
||
- 右键点击扩展图标
|
||
- 选择"选项"或"管理扩展"
|
||
- 启用所有必需权限
|
||
|
||
2. **检查清单权限**：
|
||
|
||
```json
|
||
{
|
||
"permissions": [
|
||
"nativeMessaging",
|
||
"tabs",
|
||
"activeTab",
|
||
"scripting",
|
||
"notifications",
|
||
"downloads",
|
||
"webRequest",
|
||
"debugger",
|
||
"history",
|
||
"bookmarks",
|
||
"offscreen",
|
||
"storage"
|
||
],
|
||
"host_permissions": ["<all_urls>"]
|
||
}
|
||
```
|
||
|
||
## 🖥️ 原生服务器问题
|
||
|
||
### 服务器无法启动
|
||
|
||
**问题**：原生服务器启动失败
|
||
|
||
```
|
||
Error: listen EADDRINUSE :::12306
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查端口可用性**：
|
||
|
||
```bash
|
||
# 检查端口 12306 是否被占用
|
||
lsof -i :12306
|
||
netstat -an | grep 12306
|
||
|
||
# 终止占用端口的进程
|
||
kill -9 <PID>
|
||
```
|
||
|
||
2. **使用不同端口**：
|
||
|
||
```bash
|
||
# 设置自定义端口
|
||
export NATIVE_SERVER_PORT=12307
|
||
mcp-chrome-bridge
|
||
```
|
||
|
||
### 找不到原生消息主机
|
||
|
||
**问题**：Chrome 找不到原生消息主机
|
||
|
||
```
|
||
Error: Specified native messaging host not found
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **重新安装原生主机**：
|
||
|
||
```bash
|
||
cd app/native-server
|
||
npm uninstall -g mcp-chrome-bridge
|
||
npm install -g .
|
||
```
|
||
|
||
2. **手动安装清单**：
|
||
|
||
```bash
|
||
# 创建清单目录
|
||
mkdir -p ~/.config/google-chrome/NativeMessagingHosts/
|
||
|
||
# 复制清单
|
||
cp native-messaging-manifest.json ~/.config/google-chrome/NativeMessagingHosts/com.chromemcp.nativehost.json
|
||
```
|
||
|
||
## 🔗 MCP 协议问题
|
||
|
||
### MCP 客户端连接问题
|
||
|
||
**问题**：Claude Desktop 无法连接到 MCP 服务器
|
||
|
||
```
|
||
Error: Failed to connect to MCP server
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查 MCP 配置**：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"chrome-mcp-server": {
|
||
"command": "mcp-chrome-bridge",
|
||
"args": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
2. **验证服务器运行**：
|
||
|
||
```bash
|
||
# 检查服务器是否监听
|
||
curl http://localhost:12306/health
|
||
```
|
||
|
||
3. **检查日志**：
|
||
|
||
```bash
|
||
# 原生服务器日志
|
||
tail -f ~/.local/share/mcp-chrome-bridge/logs/server.log
|
||
|
||
# Chrome 扩展日志
|
||
# 打开 Chrome DevTools -> 扩展 -> 后台脚本
|
||
```
|
||
|
||
### 工具执行超时
|
||
|
||
**问题**：工具执行期间超时
|
||
|
||
```
|
||
Error: Tool execution timeout after 30000ms
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **增加超时时间**：
|
||
|
||
```typescript
|
||
// 在原生服务器配置中
|
||
const response = await nativeMessagingHostInstance.sendRequestToExtensionAndWait(
|
||
request,
|
||
NativeMessageType.CALL_TOOL,
|
||
60000, // 增加到 60 秒
|
||
);
|
||
```
|
||
|
||
2. **检查 Chrome 扩展响应性**：
|
||
- 打开 Chrome DevTools
|
||
- 检查 JavaScript 错误
|
||
- 监控内存使用
|
||
|
||
## 🧠 AI/SIMD 问题
|
||
|
||
### SIMD 不可用
|
||
|
||
**问题**：SIMD 加速不工作
|
||
|
||
```
|
||
Warning: SIMD not supported, using JavaScript fallback
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查浏览器支持**：
|
||
|
||
- Chrome 91+（2021年5月）
|
||
- Firefox 89+（2021年6月）
|
||
- Safari 16.4+（2023年3月）
|
||
- Edge 91+（2021年5月）
|
||
|
||
2. **启用 SIMD 标志**（如需要）：
|
||
|
||
```
|
||
# Chrome 标志
|
||
chrome://flags/#enable-webassembly-simd
|
||
```
|
||
|
||
3. **验证 WASM 构建**：
|
||
|
||
```bash
|
||
cd packages/wasm-simd
|
||
pnpm build
|
||
# 检查 pkg/ 中的 simd_math.js 和 simd_math_bg.wasm
|
||
```
|
||
|
||
### AI 模型加载失败
|
||
|
||
**问题**：语义相似度引擎初始化失败
|
||
|
||
```
|
||
Error: Failed to load AI model
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查模型文件**：
|
||
|
||
```bash
|
||
# 验证模型文件存在
|
||
ls app/chrome-extension/public/models/
|
||
# 应包含 model.onnx、tokenizer.json 等
|
||
```
|
||
|
||
2. **清除浏览器缓存**：
|
||
|
||
- 打开 Chrome DevTools
|
||
- 应用程序标签 -> 存储 -> 清除存储
|
||
|
||
3. **检查内存使用**：
|
||
- 监控 Chrome 任务管理器
|
||
- 确保有足够的 RAM（推荐 >2GB）
|
||
|
||
### 向量数据库问题
|
||
|
||
**问题**：向量搜索不工作
|
||
|
||
```
|
||
Error: Vector database initialization failed
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **清除 IndexedDB**：
|
||
|
||
- Chrome DevTools -> 应用程序 -> IndexedDB
|
||
- 删除"VectorDatabase"条目
|
||
|
||
2. **检查 WASM 加载**：
|
||
|
||
```javascript
|
||
// 在浏览器控制台中
|
||
console.log(typeof WebAssembly);
|
||
// 应返回 "object"
|
||
```
|
||
|
||
## ⚡ 性能问题
|
||
|
||
### 高内存使用
|
||
|
||
**问题**：扩展使用过多内存（>500MB）
|
||
|
||
**解决方案**：
|
||
|
||
1. **减少缓存大小**：
|
||
|
||
```typescript
|
||
// 在 semantic-similarity-engine.ts 中
|
||
const config = {
|
||
cacheSize: 100, // 从默认 500 减少
|
||
maxElements: 5000, // 减少向量数据库大小
|
||
};
|
||
```
|
||
|
||
2. **定期清除缓存**：
|
||
|
||
```javascript
|
||
// 清除嵌入缓存
|
||
semanticEngine.clearCache();
|
||
|
||
// 清除向量数据库
|
||
vectorDatabase.clear();
|
||
```
|
||
|
||
### 工具执行缓慢
|
||
|
||
**问题**：工具执行超过 5 秒
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查内容脚本注入**：
|
||
|
||
```javascript
|
||
// 验证脚本已缓存
|
||
chrome.scripting.getRegisteredContentScripts();
|
||
```
|
||
|
||
2. **优化选择器**：
|
||
|
||
```javascript
|
||
// 使用高效选择器
|
||
'#specific-id'; // 好
|
||
'.class-name'; // 可以
|
||
'div > span.class'; // 比复杂选择器好
|
||
```
|
||
|
||
3. **监控性能**：
|
||
|
||
```javascript
|
||
// 添加计时日志
|
||
console.time('tool-execution');
|
||
// ... 工具代码 ...
|
||
console.timeEnd('tool-execution');
|
||
```
|
||
|
||
## 🌐 网络捕获问题
|
||
|
||
### 没有捕获到请求
|
||
|
||
**问题**：网络捕获返回空结果
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查权限**：
|
||
|
||
- 确保授予"webRequest"权限
|
||
- 验证主机权限包含目标域
|
||
|
||
2. **验证捕获时机**：
|
||
|
||
```javascript
|
||
// 在导航前开始捕获
|
||
await callTool('chrome_network_capture_start');
|
||
await callTool('chrome_navigate', { url: 'https://example.com' });
|
||
// 等待页面加载
|
||
await new Promise((resolve) => setTimeout(resolve, 3000));
|
||
await callTool('chrome_network_capture_stop');
|
||
```
|
||
|
||
3. **检查过滤器**：
|
||
- 如需要，禁用静态资源过滤
|
||
- 验证 URL 模式匹配
|
||
|
||
### Debugger API 问题
|
||
|
||
**问题**：调试器捕获失败
|
||
|
||
```
|
||
Error: Cannot attach debugger to this target
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
1. **检查标签页状态**：
|
||
|
||
- 确保标签页不是 Chrome 内部页面
|
||
- 验证标签页已完全加载
|
||
|
||
2. **分离现有调试器**：
|
||
|
||
```javascript
|
||
// 在 Chrome DevTools 控制台中
|
||
chrome.debugger.getTargets().then((targets) => {
|
||
targets.forEach((target) => {
|
||
if (target.attached) {
|
||
chrome.debugger.detach({ targetId: target.id });
|
||
}
|
||
});
|
||
});
|
||
```
|
||
|
||
## 🆘 获取帮助
|
||
|
||
如果您仍然遇到问题：
|
||
|
||
1. **检查 GitHub Issues**：[github.com/hangwin/chrome-mcp-server/issues](https://github.com/hangwin/chrome-mcp-server/issues)
|
||
|
||
2. **创建错误报告**，包含：
|
||
|
||
- 操作系统和版本
|
||
- Chrome 版本
|
||
- Node.js 版本
|
||
- 完整错误消息
|
||
- 重现步骤
|
||
|
||
3. **启用调试日志**：
|
||
|
||
```bash
|
||
# 设置调试环境
|
||
export DEBUG=chrome-mcp-server:*
|
||
mcp-chrome-bridge
|
||
```
|
||
|
||
4. **收集日志**：
|
||
|
||
- Chrome 扩展控制台日志
|
||
- 原生服务器日志
|
||
- MCP 客户端日志
|
||
|
||
5. **使用最小设置测试**：
|
||
- 新的 Chrome 配置文件
|
||
- 干净安装
|
||
- 默认配置
|
||
|
||
报告问题时请记得包含相关日志和系统信息！
|