【2026 最新】Chrome DevTools MCP 教學：讓 Claude Code 用 Console、Network、DOM 驗收前端

你請 Claude Code 修好一個前端 bug，它改了程式、測試也綠了，最後回你一句「完成」。這正是 Chrome DevTools MCP 應該上場的時刻：瀏覽器裡真的沒有紅字嗎？失敗的 API 有沒有變成 200？按鈕旁的「已儲存」究竟是畫面文字，還是程式狀態真的正確？只看 agent 的回答，等於請修車師傅口頭保證煞車好了，卻沒有試踩。

Chrome DevTools MCP 的價值，不是讓 AI 自己亂點網頁，而是把瀏覽器 runtime 變成可查驗的證據來源。它讓 Claude Code 能透過 Chrome DevTools 讀 Console、Network、頁面結構、截圖與 Performance trace，再把觀察改寫成可重跑的 assertion（明確的通過條件）。這篇專為第一次建立 agent 驗收流程的讀者寫：從隔離設定、受控 bug、修補，到輸出 before／after receipt，一次走完。

先說結論：可靠驗收不是「AI 說好了」

可靠驗收 ＝ Observation（看見）＋ Assertion（可推翻的條件）＋ Receipt（前後證據包）。

Observation 是 Console error、HTTP status、DOM attribute、畫面與 trace；Assertion 是「不能出現 SAVE_FAILED」「PUT /api/preferences 必須回 200」這種會明確失敗的規則；Receipt 則保存版本、操作、結果與檔案，讓下一個人能重跑。少任何一項都不完整：只有觀察會變成截圖收藏，只有 assertion 會缺少診斷線索，只有 receipt 則可能把錯誤完整封存。

如果你還不熟 agent 的工具層，可以先讀 AI Agent Harness 是什麼；若已經在設計整套 coding workflow，則搭配 AI Agent Harness 實作教學會更容易看出：Chrome DevTools MCP 是 harness 裡的「瀏覽器感測器」，不是替代所有測試的萬用機器人。

Chrome DevTools MCP 到底接通了什麼？

MCP（Model Context Protocol）可以想成 agent 與外部工具之間的標準插座。Chrome DevTools MCP v1.8.0把 Chrome 的除錯能力包成工具：Claude Code 先取得 pageId，再導覽、點擊、讀訊息、查 request、執行窄範圍 JavaScript 或存圖。它沒有讓模型「更懂前端」，而是讓模型的判斷能對照 runtime。

1. Console：list_console_messages找 error／warning，必要時用 get_console_message追一筆訊息與 stack。
2. Network：list_network_requests先找失敗 request，再用 get_network_request看 status 與必要細節。
3. 頁面結構：take_snapshot讀的是 accessibility tree（無障礙樹）與可互動 UID，不是 raw DOM dump；精確的 attribute、文字或 computed style 要用 evaluate_script。
4. 畫面：take_screenshot保存 viewport、全頁或單一 UID 元素，適合證明使用者實際看見什麼。
5. 性能：performance_start_trace與 performance_stop_trace保存一次受控互動；若要主張 LCP、INP 或 CLS 改善，再針對回傳的 insight 深挖。

這五種證據回答的是不同問題。DOM 正確不代表 request 成功，HTTP 200 不代表畫面有更新，截圖漂亮也不代表 Console 沒有 exception。要建立可維護的 agent，不只要「看得到」，還要知道每一個感測器能證明到哪裡；這也是 Agent 可觀測性的核心觀念。

第 1 步：先裝一個不碰真實帳號的測試瀏覽器

截至 2026 年 9 月 6 日，npm 與 GitHub 最新正式版都是 v1.8.0；本文把版本釘住，避免明天的 @latest改變工具 schema。依官方需求，先準備 Node.js LTS、npm 與目前穩定版 Chrome。若只要 MCP、不要一併安裝官方 Claude Code skills，可在終端機貼上：

claude mcp add --transport stdio --scope user chrome-devtools -- \
  npx -y chrome-devtools-mcp@1.8.0 \
  --headless --isolated --viewport=1280x720 \
  '--allowed-url-pattern=http://127.0.0.1:4173/*' \
  --redact-network-headers \
  --no-performance-crux --no-usage-statistics

--isolated會建立暫時 user-data directory，Chrome 關閉後清理；--allowed-url-pattern把導覽與 subresource 限在測試站（需 Chrome 149 以上）；--redact-network-headers遮蔽部分敏感 header；後兩個 --no-*分別停用 trace URL 的 CrUX 查詢與預設 usage statistics。安裝後執行 claude mcp get chrome-devtools，再到 Claude Code 輸入 /mcp確認連線。

這是一組依官方 v1.8.0 參數組成的教學設定，不是一鍵安全保證。URL pattern 只是連在 DevTools target 上的瀏覽器 guardrail，不是完整網路 sandbox；header redaction 也不會替你刪掉 response body、DOM、Console、截圖或 trace 裡的祕密。只放假資料、測試帳號與本機站點；需要更完整隔離時，邊界應放到專用 OS 使用者、容器或 VM。

不要為了省一步而 auto-connect 到日常 Chrome。既有 session 可能帶著 tabs、cookies、local storage 與登入狀態，agent 也能代表該使用者操作。想理解「共享登入瀏覽器」和「隔離 profile」的差別，可接著看 讓 AI Agent 使用瀏覽器登入狀態的隔離教學。

第 2 步：定義一個可以被推翻的 bug

假設本機 /settings有「儲存設定」按鈕。測試 fixture 故意讓 PUT /api/preferences回 500，但前端的 finally仍把 #save-status設為 data-state="success"並顯示「已儲存」。這個案例不是聲稱 AlphaLab 跑過你的專案，而是依 v1.8.0 工具契約設計的可重跑腳本；你要在自己的 repo、commit 與測試資料上取得結果。

先把通過條件寫在修補之前：

• 重現這次操作後，Console 不得出現 SAVE_FAILED。
• PUT /api/preferences必須回 200。
• #save-status必須同時符合 data-state="success"與文字「已儲存」。
• after screenshot 要顯示成功狀態，且與同 viewport 的 before 圖可配對。
• 只有當任務本來就在修性能，才替 trace 寫數字門檻；本例追正確性，不從單次 trace 宣稱「變快」。

這一步看似慢，實際上是在阻止 agent 偷換問題。沒有 assertion，它可能只把 console.error刪掉，就宣布 Console 乾淨；但 API 仍然 500，使用者照樣收到假的成功訊息。

第 3 步：把「請修好」改成證據導向 prompt

把下面這段交給 Claude Code。重點不是逐字背工具，而是限制網域、先存 before、最小修改、再用同條件重跑：

只操作 http://127.0.0.1:4173/settings 與測試資料。
先 list_pages 取得 pageId，導覽／reload 後再重現一次。
在改 code 前保存：
1. Console 中與 SAVE_FAILED 有關的訊息與 stack
2. PUT /api/preferences 的 status（除非診斷必要，不讀 body）
3. 最新 accessibility snapshot
4. 用 evaluate_script 回傳 #save-status 的 textContent 與 data-state
5. 1280×720 viewport screenshot
6. 一份互動 trace；本次不據此主張性能改善

指出哪一項 assertion 失敗，做最小修補，清 cache reload，
在相同 viewport 與步驟下重跑。最後輸出 before/after receipt；
不得把 cookies、Authorization、response body 或個資放進報告。

為什麼要「導覽／reload 後再重現」？v1.8.0 的 Console 與 Network 清單以最近一次 navigation 為主要範圍；你若先點了十輪才叫 agent 收集，證據容易混在舊狀態裡。這版也預設啟用 page-ID routing，page-scoped 工具要帶 pageId，所以第一步先 list_pages，不要把別的 tab 當成受測頁。

第 4 步：依序收 Console、Network、結構與畫面

① Console 先找症狀。用 list_console_messages篩 error，開啟 stack 資訊，再用 msgid取得與儲存操作相關的一筆。不要把「error 數量變零」單獨當修好；它只能證明瀏覽器沒再印出那類訊息。

② Network 找因果邊界。用 list_network_requests找到 PUT /api/preferences，以 reqid查 status。get_network_request能看到 headers 甚至 body，權限因此比一般 request 清單大；若 status 已足夠，就不要多拿資料。before 預期是 500，after 必須是 200。

③ Snapshot 找可操作位置，JavaScript 找精確事實。take_snapshot適合讀角色、accessible name 與 UID；若 assertion 是 attribute，請用窄 selector：

() => {
  const el = document.querySelector('#save-status');
  return el ? {
    text: el.textContent?.trim(),
    state: el.getAttribute('data-state')
  } : { missing: true };
}

回傳必須能序列化成 JSON。若 before 得到 {"text":"已儲存","state":"success"}，同時 Network 卻是 500，這個「跨證據矛盾」才是真正的 bug，不是單一工具的猜測。

④ Screenshot 證明使用者看見的結果。用固定 1280×720 viewport 存 before.png；修補後用同一頁面狀態存 after.png。不要一張截全頁、一張只截按鈕，也不要在兩次之間改 theme 或 viewport，否則 diff 失去意義。

⑤ Trace 只回答性能問題。先導覽到目標頁，再用 performance_start_trace包住明確互動，結束後存私有的 .json.gz。一條 trace 很適合找主執行緒阻塞、LCP／INP／CLS 線索；它不是統計顯著的 benchmark。若任務沒寫性能 assertion，就把 trace 標成診斷附件，不要硬湊「提升 30%」。

第 5 步：修補後用同一把尺重跑

本例的最小修補，是只在 response.ok之後設定 success；失敗分支改成 error state，再保留能追查的例外。完成後用 navigate_page做 reload、忽略 cache，照完全相同的點擊與收集順序重跑。Receipt 不必華麗，但至少要能回答「測了哪個版本、在哪個環境、哪條規則通過」。

{
  "scope": {
    "commit": "<git-sha>",
    "url": "http://127.0.0.1:4173/settings",
    "chrome": "<version>",
    "mcp": "1.8.0",
    "viewport": "1280x720"
  },
  "assertions": {
    "console": "collector-on reload: no matching SAVE_FAILED",
    "network": "PUT /api/preferences = 200",
    "dom": { "state": "success", "text": "已儲存" },
    "visual": ["before.png", "after.png"]
  },
  "performance": {
    "claim": "none for this correctness fix",
    "artifact": "after-trace.json.gz"
  }
}

保存前先人工看一次內容：request body、headers、DOM 文字與截圖都可能含個資或 token。Receipt 應進私有 artifact storage 或短期 CI artifact，不要因為它叫「測試證據」就直接 commit。若你還在建立 incident／rollback 的證據習慣，Coding Agent 事故復原演練提供了更完整的 stop condition 與 rollback 思路。

這張 receipt 能支持的結論也要寫窄：在記錄的 Chrome、MCP、viewport、profile 與網路設定下，collector 啟用後的這次 reload 符合 assertion；它沒有替其他瀏覽器、帳號狀態或網路條件背書。

Full、Slim、Tool Search 與 CLI 怎麼選？

v1.8.0 的預設 server 有 29 個工具；--slim只留下 navigate、evaluate、screenshot三個基本工具。AlphaLab 對同一版本做 tools/list JSON 快照，完整模式是 25,796 UTF-8 bytes，slim 是 1,027 bytes。這是server 回傳的工具定義大小，不是 token 數，也不是 Claude Code 每次都塞進 context 的成本。

截至 2026 年 9 月 6 日，Claude Code 官方文件說 Tool Search 預設會延後載入 MCP 工具定義，因此「29 個 schema 一定全程佔滿 context」已不是正常設定下的可靠說法；舊模型、第三方 provider、停用 Tool Search 或把工具標成 always-load，行為才可能不同。工具輸出太大則是另一件事：拿整包 response body 或長 trace 回對話，仍會膨脹 context。

• 選 Full：你正在診斷未知 bug，需要 Console、Network、snapshot 或 performance。本文的完整證據鏈必須用它。
• 選 Slim：任務只要開頁、執行一小段查詢、截圖，且不需要 DevTools 診斷通道。它不是 Full 的「比較快保證」，只是較小的工具面。
• 改成既有測試 runner／CLI：assertion 已穩定、會在每次 commit 重跑、要 machine-readable exit code 與 CI artifact。MCP 很適合探索和把模糊症狀變規則；固定規則通常應回到 Playwright、Vitest 或團隊既有測試系統。若採官方仍標示 experimental 的 Chrome DevTools CLI，也要 pin 版本並驗證輸出契約。

最常踩的 5 個坑

1. 把新視窗當乾淨環境：預設專用 profile 可跨執行保留；要一次性測試就明確加 --isolated。
2. 把 snapshot 當 DOM：它是 accessibility tree。角色與 UID 用 snapshot，attribute 與 computed style 用 evaluate_script。
3. 只看 after：沒有同條件的 before，就不知道修補造成差異，還是資料與 viewport 剛好變了。
4. 收集越多越安心：整包 headers、body、長 trace 會同時增加敏感資料與 context 成本。Assertion 需要什麼才取什麼。
5. 把一次 trace 當 benchmark：一次 trace 能定位線索，不能支撐穩定的百分比結論；性能回歸要固定環境、定義指標並重複取樣。

Chrome DevTools MCP 常見問題 FAQ

1. 它可以取代 Playwright 或單元測試嗎？

不能。MCP 適合讓 agent 探索 runtime、找出可驗證規則；成熟 assertion 應沉澱到可由 CI 穩定執行的測試。兩者是偵查與守門的分工。

2. take_snapshot就是 DOM 快照嗎？

不是。v1.8.0 的工具參考把它定義成基於 accessibility tree 的文字快照；要驗 class、attribute、bounding box 或 computed style，改用窄範圍 evaluate_script。

3. 加了 --isolated就安全了嗎？

不等於。它隔離 profile 狀態，沒有阻止 agent 讀受測頁內容，也不是完整網路／檔案 sandbox。仍要用假資料、限制站點與最小化輸出。

4. 可以直接連我已登入的 Chrome 嗎？

技術上有既有瀏覽器連線方式，但不適合這份教學。它會把該 profile 的分頁、cookies、storage 與可操作權限放進信任邊界；回歸驗收用專用測試 profile。

5. 開了 Tool Search，還需要 Slim 嗎？

不一定。Tool Search處理 client 何時載入 schema；Slim 則直接縮小 server 可呼叫的能力面。只做基本瀏覽可選 Slim，診斷本文 bug 則要 Full。

6. Network header redaction 會移除所有祕密嗎？

不會這樣保證。官方描述的範圍是部分敏感 network headers；body、Console、DOM、storage、截圖與 trace 要分開審查。

7. 一次 before／after trace 能證明性能變快嗎？

不能證明穩定提升。它能指出候選瓶頸與同條件 smoke comparison；正式性能結論需要固定環境、重複樣本與事先定義的門檻。

8. Microsoft Edge 也能用嗎？

Microsoft 有發布 Edge／WebView2 的設定教學。但 Chrome 專案 v1.8.0 的官方支援範圍寫的是 Google Chrome 與 Chrome for Testing；若改用 Edge，請依 Microsoft walkthrough驗證可執行檔、profile 與連線流程，不要把 Chromium 相容性當成同一份支援承諾。

結語：讓 agent 交作業，也交驗收收據

Chrome DevTools MCP 最值得帶走的，不是一串工具名稱，而是開頭那個公式：可靠驗收 ＝ Observation ＋ Assertion ＋ Receipt。今天先挑一個最小、最熟悉的本機 bug，固定 profile、URL、viewport 與重現步驟；改 code 前存 before，改完後用同一把尺重跑。當 agent 必須說清楚「哪條規則從紅變綠」，你才真正把「看起來修好了」變成工程證據。

想把單次練習擴成完整 AI 開發工作流，可以從 AlphaLab 的 AI 實戰課程繼續，把工具選擇、context 管理、測試與交付串成自己的 harness。