mcp-chrome/docs/TROUBLESHOOTING_zh.md

故障排除指南 🔧

Chrome MCP Server 的常见问题和解决方案。

📋 目录

• 安装问题
• Chrome 扩展问题
• 原生服务器问题
• MCP 协议问题
• AI/SIMD 问题
• 性能问题
• 网络捕获问题

🚀 安装问题

Node.js 版本兼容性

问题：构建失败，出现 Node.js 版本错误

Error: Unsupported Node.js version

解决方案：

# 检查 Node.js 版本
node --version

# 如需要，安装 Node.js 18+
# 使用 nvm（推荐）
nvm install 18
nvm use 18

# 或从 nodejs.org 下载

pnpm 安装问题

问题：找不到 pnpm 命令

bash: pnpm: command not found

解决方案：

# 全局安装 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

解决方案：

# 清理并重新构建
pnpm clean
pnpm install
pnpm build

# 检查特定包问题
pnpm build:shared
pnpm build:wasm
pnpm build:native
pnpm build:extension

🔌 Chrome 扩展问题

扩展无法加载

问题：扩展在 Chrome 中加载失败

症状：

• "清单文件丢失或不可读"
• "无效清单"
• 扩展显示为灰色

解决方案：

1. 检查构建输出：

cd app/chrome-extension
pnpm build
# 验证 dist/ 目录存在且包含 manifest.json

2. 验证 manifest.json：

cat app/chrome-extension/dist/manifest.json
# 应包含有效的 JSON 和版本 3

3. 启用开发者模式：
   • 转到 chrome://extensions/
   • 打开"开发者模式"
   • 点击"加载已解压的扩展程序"
   • 选择 app/chrome-extension/dist

原生消息连接失败

问题：扩展无法连接到原生服务器

Error: Native host has exited

解决方案：

1. 检查原生服务器安装：

# 验证全局安装
npm list -g mcp-chrome-bridge

# 如需要，重新安装
cd app/native-server
npm install -g .

2. 验证原生消息清单：

# 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. 检查权限：

# 确保可执行权限
chmod +x /path/to/mcp-chrome-bridge

扩展权限被拒绝

问题：扩展缺少必要权限

解决方案：

1. 手动授予权限：

   • 右键点击扩展图标
   • 选择"选项"或"管理扩展"
   • 启用所有必需权限

2. 检查清单权限：

{
  "permissions": [
    "nativeMessaging",
    "tabs",
    "activeTab",
    "scripting",
    "notifications",
    "downloads",
    "webRequest",
    "debugger",
    "history",
    "bookmarks",
    "offscreen",
    "storage"
  ],
  "host_permissions": ["<all_urls>"]
}

🖥️ 原生服务器问题

服务器无法启动

问题：原生服务器启动失败

Error: listen EADDRINUSE :::12306

解决方案：

1. 检查端口可用性：

# 检查端口 12306 是否被占用
lsof -i :12306
netstat -an | grep 12306

# 终止占用端口的进程
kill -9 <PID>

2. 使用不同端口：

# 设置自定义端口
export NATIVE_SERVER_PORT=12307
mcp-chrome-bridge

找不到原生消息主机

问题：Chrome 找不到原生消息主机

Error: Specified native messaging host not found

解决方案：

1. 重新安装原生主机：

cd app/native-server
npm uninstall -g mcp-chrome-bridge
npm install -g .

2. 手动安装清单：

# 创建清单目录
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 配置：

{
  "mcpServers": {
    "chrome-mcp-server": {
      "command": "mcp-chrome-bridge",
      "args": []
    }
  }
}

2. 验证服务器运行：

# 检查服务器是否监听
curl http://localhost:12306/health

3. 检查日志：

# 原生服务器日志
tail -f ~/.local/share/mcp-chrome-bridge/logs/server.log

# Chrome 扩展日志
# 打开 Chrome DevTools -> 扩展 -> 后台脚本

工具执行超时

问题：工具执行期间超时

Error: Tool execution timeout after 30000ms

解决方案：

1. 增加超时时间：

// 在原生服务器配置中
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 构建：

cd packages/wasm-simd
pnpm build
# 检查 pkg/ 中的 simd_math.js 和 simd_math_bg.wasm

AI 模型加载失败

问题：语义相似度引擎初始化失败

Error: Failed to load AI model

解决方案：

1. 检查模型文件：

# 验证模型文件存在
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 加载：

// 在浏览器控制台中
console.log(typeof WebAssembly);
// 应返回 "object"

⚡ 性能问题

高内存使用

问题：扩展使用过多内存（>500MB）

解决方案：

1. 减少缓存大小：

// 在 semantic-similarity-engine.ts 中
const config = {
  cacheSize: 100, // 从默认 500 减少
  maxElements: 5000, // 减少向量数据库大小
};

2. 定期清除缓存：

// 清除嵌入缓存
semanticEngine.clearCache();

// 清除向量数据库
vectorDatabase.clear();

工具执行缓慢

问题：工具执行超过 5 秒

解决方案：

1. 检查内容脚本注入：

// 验证脚本已缓存
chrome.scripting.getRegisteredContentScripts();

2. 优化选择器：

// 使用高效选择器
'#specific-id'; // 好
'.class-name'; // 可以
'div > span.class'; // 比复杂选择器好

3. 监控性能：

// 添加计时日志
console.time('tool-execution');
// ... 工具代码 ...
console.timeEnd('tool-execution');

🌐 网络捕获问题

没有捕获到请求

问题：网络捕获返回空结果

解决方案：

1. 检查权限：

   • 确保授予"webRequest"权限
   • 验证主机权限包含目标域

2. 验证捕获时机：

// 在导航前开始捕获
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. 分离现有调试器：

// 在 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

2. 创建错误报告，包含：

   • 操作系统和版本
   • Chrome 版本
   • Node.js 版本
   • 完整错误消息
   • 重现步骤

3. 启用调试日志：

# 设置调试环境
export DEBUG=chrome-mcp-server:*
mcp-chrome-bridge

4. 收集日志：

   • Chrome 扩展控制台日志
   • 原生服务器日志
   • MCP 客户端日志

5. 使用最小设置测试：

   • 新的 Chrome 配置文件
   • 干净安装
   • 默认配置

报告问题时请记得包含相关日志和系统信息！