chrome-devtools-mcp：让 AI 编码助手真正"看见"浏览器由 Google Chrome DevToo

引子：AI 写代码最大的盲区

你一定遇到过这种循环：

你：帮我修一下这个页面的布局错位
AI：可能是 flex 容器的 min-width 问题，试试加 min-w-0
你：没用
AI：那试试 overflow-hidden？
你：也没用
AI：再试试……

问题不在于模型不够聪明，而在于它看不见。它读的是源码，推理的是"通常是什么原因"，但真正的原因可能藏在 computed style 的层叠顺序里、藏在某次网络请求的 302 里、藏在一条被 source map 混淆过的 console 报错里。

chrome-devtools-mcp 就是 Google 官方给出的答案：把 Chrome DevTools 的完整能力，通过 MCP（Model Context Protocol）交给 AI 编码助手。

一、chrome-devtools-mcp 是什么？

一句话定义

它是一个由 Google Chrome DevTools 团队官方维护的 MCP Server，让你的编码 Agent（Claude Code、Codex、Gemini CLI、Cursor、Copilot 等）能够控制并审查一个真实的、活着的 Chrome 浏览器。

三个官方主打特性

性能洞察（Performance insights） — 录制 trace 并提取可行动的结论，而不是甩给你一个 .json trace 文件。还能结合 CrUX 真实用户数据（field data）与实验室数据（lab data）对照。
深度浏览器调试 — 网络请求分析、截图、console 消息（带 source map 还原后的调用栈）。最后这一条很关键：AI 看到的报错堆栈是你写的 Button.tsx:42，而不是打包产物里的 chunk-7a3f.js:1:8932。
可靠的自动化 — 底层用 Puppeteer 执行动作，并且自动等待动作结果。这一点比"点一下然后 sleep 2 秒"的玩法稳健得多。

设计上的一个巧思：`take_snapshot` 优先于截图

官方明确建议：优先用 take_snapshot 而不是 take_screenshot。

take_snapshot 返回的是基于 a11y 树的文本快照，每个元素带一个唯一 uid。这意味着：

元素定位不依赖脆弱的 CSS 选择器；
消耗的是文本 token，不是图片 token（截图一张动辄上千 token）；
天然带语义信息（role、name、state）。

后续所有交互类工具（click / fill / hover / drag）都通过 uid 定位元素。这是一个非常"为 LLM 设计"的决策。

二、有什么用？

工具全景（11 大类 / 59 个工具）

分类	数量	代表工具	典型场景
Input 输入自动化	10	`click`、`fill`、`fill_form`、`drag`、`press_key`、`upload_file`	模拟真实用户操作
Navigation 导航	6	`new_page`、`navigate_page`、`wait_for`、`list_pages`	多标签页管理
Emulation 模拟	2	`emulate`、`resize_page`	移动端视口、弱网、CPU 降速、地理位置
Performance 性能	3	`performance_start_trace` / `_stop_trace` / `performance_analyze_insight`	Core Web Vitals 诊断
Network 网络	2	`list_network_requests`、`get_network_request`	查 4xx/5xx、排查 CORS、看 Cookie/Set-Cookie
Debugging 调试	9	`take_snapshot`、`take_screenshot`、`evaluate_script`、`list_console_messages`、`get_css_styles`、`lighthouse_audit`	日常 Debug 主力
Memory 内存	14	`take_heapsnapshot`、`get_heapsnapshot_retaining_paths`、`compare_heapsnapshots`	内存泄漏定位（需 `--memoryDebugging=true`）
Extensions 扩展	5	`install_extension`、`list_extensions`	默认关闭，需 `--categoryExtensions=true`
Third-party 第三方	2	`list_3p_developer_tools`	默认关闭
WebMCP	2	`list_webmcp_tools`、`execute_webmcp_tool`	默认关闭，需 Chrome 150+ 加 `--enable-features=WebMCP`
PWA	4	`install_pwa`、`launch_pwa`	默认关闭

六个真正落地的使用场景

1. 让 AI 自己复现 Bug，而不是猜 Bug

我登录后点「提交订单」没反应，帮我看看为什么

Agent 会：打开页面 → fill_form 填登录表单 → click 提交 → list_console_messages 拉报错 → list_network_requests 看接口是不是 500 → evaluate_script 验证状态。全程自己走一遍，结论有证据。

2. UI 改动的自证闭环

改完样式后：

把移动端视口调成 375x812，看看导航栏在 iPhone 上有没有溢出

resize_page → take_snapshot / take_screenshot → 自己判断 → 自己改。这一步以前需要你手动截图贴给 AI。

3. 性能问题定位到具体 Insight

Check the performance of https://developers.chrome.com

这是官方推荐的"第一条提示词"，用来验证安装是否成功。Agent 会录制 trace 并返回结构化的性能洞察（LCP / INP / CLS 等）。注意：Lighthouse 的 lighthouse_audit 不含性能部分，性能要走 performance_start_trace。

4. 无障碍与 SEO 的提交前体检

Run a Lighthouse accessibility audit and suggest fixes for any low-contrast elements.

lighthouse_audit 覆盖 accessibility / SEO / best practices，输出的是可勾选的整改清单。

5. 表单与多步流程的 E2E 冒烟

一次 fill_form 批量填完用户名、密码、勾选框，比拆成多次 fill + click 更快更稳（官方明确建议优先用 fill_form）。

6. 内存泄漏排查

take_heapsnapshot 存文件 → compare_heapsnapshots 对比两次快照 → get_heapsnapshot_retaining_paths 查谁在持有引用。以前这是要手动点 DevTools Memory 面板的活儿。

三、主流工具如何安装

通用配置（所有支持 `mcpServers` 的客户端）

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

最直接、最直白的安装方式，在任何智能体的对话框里面输入：“帮我安装chrome-devtools-mcp”

四、参数配置

所有参数通过 args 数组传递：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--channel=canary",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

也可以统一写进 JSON 文件，用 --config /path/to/config.json 加载。随时用 npx chrome-devtools-mcp@latest --help 查全量参数。

4.1 浏览器启动与连接

参数	类型	默认	说明
`--headless`	boolean	`false`	无 UI 模式，CI 必备
`--channel`	enum	`stable`	可选 `stable` / `beta` / `dev` / `canary`
`--executablePath`, `-e`	string	—	自定义 Chrome 可执行文件路径
`--isolated`	boolean	`false`	用临时 user-data-dir，关闭后自动清理
`--userDataDir`	string	`~/.cache/chrome-devtools-mcp/chrome-profile`	指定用户数据目录（非 stable 频道会加后缀，如 `chrome-profile-canary`）
`--browserUrl`, `-u`	string	—	连接到已开启调试端口的 Chrome，如 `http://127.0.0.1:9222`
`--wsEndpoint`, `-w`	string	—	直连 WebSocket 端点（`--browserUrl` 的替代方案）
`--wsHeaders`	string(JSON)	—	WebSocket 自定义请求头（如鉴权），仅配合 `--wsEndpoint`
`--autoConnect`	boolean	`false`	自动连接本机正在运行的 Chrome（需 Chrome 144+，且要在 `chrome://inspect/#remote-debugging` 手动开过一次）
`--viewport`	string	—	初始视口，如 `1280x720`；headless 下最大 3840x2160
`--proxyServer`	string	—	给 Chrome 传 `--proxy-server`
`--chromeArg`	array	—	追加额外的 Chrome 启动参数
`--ignoreDefaultChromeArg`	array	—	显式禁用某些默认启动参数
`--acceptInsecureCerts`	boolean	`false`	忽略自签名/过期证书错误（慎用）

4.2 工具类别开关

默认只开 6 类（Input / Navigation / Emulation / Performance / Network / Debugging / Memory 中的 take_heapsnapshot）。想精简工具集、省上下文，就把不需要的关掉：

"args": [
  "chrome-devtools-mcp@latest",
  "--categoryPerformance=false",
  "--categoryNetwork=false",
  "--categoryMemory=false"
]

参数	默认	说明
`--categoryInput`	`true`	输入自动化
`--categoryNavigation`	`true`	导航
`--categoryEmulation`	`true`	模拟
`--categoryPerformance`	`true`	性能
`--categoryNetwork`	`true`	网络
`--categoryDebugging`	`true`	调试
`--categoryMemory`	`true`	内存
`--categoryExtensions`	`false`	扩展（仅支持 pipe 连接，Chrome 149 前不兼容 autoConnect/browserUrl/wsEndpoint）
`--categoryPwa`	`false`	PWA（同样仅支持 pipe 连接）
`--categoryExperimentalThirdParty`	`false`	页面暴露的第三方开发者工具
`--categoryExperimentalWebmcp`	`false`	WebMCP 调试，需 Chrome 150+ 且加 `--enable-features=WebMCP`
`--slim`	`false`	极简模式，只留导航 + 执行脚本 + 截图 3 个工具

4.3 实验性能力

参数	默认	说明
`--experimentalVision`	`false`	启用坐标类工具 `click_at(x, y)`，通常需配合能看图出坐标的 computer-use 模型
`--experimentalDevtools`	`false`	允许自动化操作 DevTools 自身
`--experimentalScreencast`	`false`	录屏工具（需要系统装好 ffmpeg 并在 PATH 里）
`--experimentalFfmpegPath`	—	指定 ffmpeg 路径
`--experimentalScreencastFps`	number	录屏帧率，页面产帧过快时调低可减压
`--experimentalStructuredContent`	`false`	输出结构化格式化内容
`--experimentalIncludeAllPages`	`false`	把 webview、后台页等也纳为可操作 page
`--memoryDebugging`	`false`	启用 13 个堆快照分析工具（不含 `take_heapsnapshot`）
`--pageIdRouting`	`true`	页面级工具要求传 `pageId`，便于并发会话路由；用 `--no-page-id-routing` 关闭

4.4 隐私、安全与网络管控

参数	默认	说明
`--usageStatistics`	`true`	关闭：`--no-usage-statistics`。也可设环境变量 `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` 或 `CI`
`--performanceCrux`	`true`	关闭：`--no-performance-crux`，不把 trace URL 发给 Google CrUX API
`--redactNetworkHeaders`	`false`	返回前对敏感请求头做脱敏
`--blockedUrlPattern`	array	按 URL Pattern 屏蔽访问（支持 ``/`:name` 通配，不支持正则分组*）
`--allowedUrlPattern`	array	白名单模式，只允许匹配的 URL（需 Chrome 149+）
`--javascriptEvaluation`	`true`	关掉后禁用 `evaluate_script`、`navigate_page` 的 initScript，以及 `javascript:`/`data:`/`vbscript:` 导航
`--sourceMaps`	`true`	关闭：`--no-source-maps`

环境变量：CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS 可关掉启动时的 npm 版本更新检查；调试时设 DEBUG=*（日志）或 NODE_DEBUG=* 并配合 --logFile。

4.5 截图与文件系统

参数	默认	说明
`--screenshotFormat`	`png`	可选 `jpeg` / `png` / `webp`；JPEG、WebP 比 PNG 小 3–5 倍
`--screenshotQuality`	Puppeteer 默认	0–100，仅对 JPEG/WebP 生效
`--screenshotMaxWidth` / `--screenshotMaxHeight`	不限	超过则等比缩小。省 token 的关键开关（图片 token 随尺寸增长，不随字节数增长）
`--filesystemRoot`, `--workspace`	OS 临时目录	允许文件工具访问的目录，可多次指定
`--allowUnrestrictedPaths`	`false`	放开临时目录限制（仅在你完全信任本地客户端时用）

4.6 四组常用配置模板

① CI / 无头环境（推荐给自动化流水线）

{
  "command": "npx",
  "args": [
    "-y", "chrome-devtools-mcp@latest",
    "--headless=true",
    "--isolated=true",
    "--no-usage-statistics",
    "--no-performance-crux",
    "--screenshotFormat=jpeg",
    "--screenshotMaxWidth=1280"
  ]
}

② 连接你已经登录好的 Chrome（保留登录态，最实用）

先在终端起一个带调试端口的 Chrome（必须用非默认 user-data-dir）：

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable"

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

# Linux
/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

然后：

{
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
}

想更省事就用 --autoConnect（Chrome 144+）：

{ "command": "npx", "args": ["chrome-devtools-mcp@latest", "--autoConnect"] }

③ 轻量模式（只做导航 + 截图）

{
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
}

④ 多会话并发（每个会话独立浏览器）

{
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--isolated"]
}

--pageIdRouting 默认开启，页面级工具都要带 pageId，多会话不会互相串台。

4.7 三种连接模式怎么选

模式	触发方式	适用场景	代价
自己启动 Chrome	默认	一次性任务、CI、干净环境	没有你的登录态，每次新建 profile
`--browser-url` / `--wsEndpoint`	手动开调试端口	沙箱内的 Agent 连沙箱外的浏览器	调试端口对机器上所有应用开放，有安全风险
`--autoConnect`	Chrome 144+，`chrome://inspect/#remote-debugging` 授权一次	人工测试与 Agent 测试交替、需要保留登录态	需要 Chrome 144+，且每次连接会弹权限确认

chrome-devtools-mcp：让 AI 编码助手真正"看见"浏览器