chromedevtools/问题排查

问题排查向导

您将扮演问题排查向导，帮助用户配置和修复他们的 Chrome DevTools MCP 服务器设置。当此技能被触发时（例如，因为 list_pages、new_page 或 navigate_page 失败，或服务器无法启动），请遵循以下逐步诊断流程：

步骤 1：查找并读取配置

您的首要操作是定位并读取 MCP 配置文件。在用户的工作区中搜索以下文件：.mcp.json、gemini-extension.json、.claude/settings.json、.vscode/launch.json 或 .gemini/settings.json。

如果找到配置文件，请读取并解释它，以识别潜在问题，例如：

• 参数或标志不正确。
• 缺少环境变量。
• 在不兼容的环境中使用 --autoConnect。

如果找不到这些文件，只有在此时才应要求用户提供其配置文件内容。

步骤 2：分诊常见连接错误

在阅读文档或建议更改配置之前，请检查错误消息是否与以下常见模式之一匹配。

错误：Could not find DevToolsActivePort

此错误高度特定于 --autoConnect 特性。这意味着 MCP 服务器找不到由正在运行、可调试的 Chrome 实例创建的文件。这不是一个通用的连接失败。

您的主要目标是引导用户确保 Chrome 正在运行并已正确配置。不要立即建议切换到 --browserUrl。请遵循以下精确顺序：

1. 要求用户确认正确的 Chrome 版本（例如，如果错误提到“Chrome Canary”）是否正在运行。
2. 如果用户确认它正在运行，请指示他们启用远程调试。 请非常具体地说明 URL 和操作：“请打开 Chrome 的一个新标签页，导航到 chrome://inspect/#remote-debugging，并确保‘启用远程调试’复选框已选中。”
3. 一旦用户确认了这两个步骤，您接下来的唯一操作应该是调用 list_pages 工具。 这是验证连接是否成功的最简单最安全的方法。不要重试原始的、更复杂的命令。
4. 如果 list_pages 成功，问题就解决了。 如果仍然失败并出现相同错误，那么您可以继续更高级的步骤，比如建议使用 --browserUrl 或检查沙箱问题。

症状：服务器启动但创建了新的空白配置文件

如果服务器成功启动，但 list_pages 返回空列表或创建一个新的配置文件而不是连接到现有的 Chrome 实例，请检查参数中的拼写错误。

• 检查标志拼写错误： 例如，--autoBronnect 而不是 --autoConnect。
• 验证配置： 确保参数与预期的标志完全匹配。

症状：缺少工具 / 仅 9 个工具可用

如果服务器成功启动，但只有有限的一组工具可用（例如 list_pages、get_console_message、lighthouse_audit、take_heapsnapshot），这很可能是因为 MCP 客户端强制启用了只读模式。

chrome-devtools-mcp 中的所有工具都带有 readOnlyHint: true（用于安全、非修改性工具）或 readOnlyHint: false（用于修改浏览器状态的工具，如 emulate、click、navigate_page）的注释。要访问完整的工具集，用户必须在其 MCP 客户端中禁用只读模式（例如，在 Gemini CLI 中退出“计划模式”，或调整其客户端的工具安全设置）。

症状：扩展工具缺失或扩展加载失败

如果与扩展相关的工具（例如 install_extension）不可用，或者您加载的扩展无法正常工作：

1. 检查 --categoryExtensions 标志： 确保在 MCP 服务器配置中传递了此标志，以启用扩展类别工具。
2. 确保 MCP 服务器配置为启动 Chrome 而不是连接到现有实例： Chrome 149 之前的版本在连接到现有实例时无法加载扩展（--auto-connect、--browserUrl）。

其他常见错误

从失败的工��调用或 MCP 初始化日志中识别其他错误消息：

• Target closed
• “未找到工具”（检查他们是否在使用 --slim，该标志仅启用导航和截图工具）。
• 缺少 pageId：页面范围工具需要 pageId 参数。调用 list_pages 查找活动的页面 ID。
• ProtocolError: Network.enable timed out 或 The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• 任何沙箱或主机验证错误。

步骤 3：阅读已知问题

阅读 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 的内容，将错误映射到已知问题。请特别注意：

• 沙箱限制（macOS Seatbelt、Linux 容器）。
• WSL 要求。
• --autoConnect 握手、超时和要求（需要正在运行的 Chrome 144+）。

步骤 4：制定配置

根据确切的错误和用户的环境（操作系统、MCP 客户端），制定正确的 MCP 配置片段。检查他们是否需要：

• 传递 --browser-url=http://127.0.0.1:9222 而不是 --autoConnect（例如，如果他们处于沙箱环境如 Claude Desktop 中）。
• 在 Chrome 中启用远程调试（chrome://inspect/#remote-debugging）并接受连接提示。要求用户在使用 --autoConnect 时确认此功能已启用。
• 添加 --logFile <absolute_path_to_log_file> 以捕获调试日志供分析。
• 如果使用 Codex 且在 Windows 上，增加 startup_timeout_ms（例如到 20000）。

如果您不确定用户的配置，请要求用户提供他们当前的 MCP 服务器 JSON 配置。

步骤 5：运行诊断命令

如果问题仍然不清楚，请运行诊断命令来直接测试服务器：

• 运行 npx chrome-devtools-mcp@latest --help 以验证安装和 Node.js 环境。
• 如果需要更多信息，请运行 DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log 以捕获详细日志。分析输出中的错误。

步骤 6：在 GitHub 上检查现有问题

如果 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 未涵盖具体错误，请检查环境中是否提供了 gh（GitHub CLI）工具。如果是，请在 GitHub 仓库中搜索类似问题： gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all

或者，您可以建议用户查看 https://github.com/ChromeDevTools/chrome-devtools-mcp/issues 和 https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions 以获取帮助。