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. 如果使用者確認 Chrome 正在執行，請指示他們啟用遠端除錯。 請務必指定 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，而不是連接到現有實例： 149 版本之前的 Chrome 無法在連接到現有實例時載入擴充功能（--auto-connect、--browserUrl）。

其他常見錯誤

從失敗的工具呼叫或 MCP 初始化記錄中識別其他錯誤訊息：

• Target closed
• 「Tool not found」（檢查他們是否使用 --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 on 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 "<錯誤片段>" --state all

或者，您可以建議使用者查看 https://github.com/ChromeDevTools/chrome-devtools-mcp/issues 和 https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions 以尋求協助。