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

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

你一定遇到过这种循环：

arduino 复制代码

你：帮我修一下这个页面的布局错位
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

arduino 复制代码

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

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

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

arduino 复制代码

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` 的客户端）

json 复制代码

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

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

四、参数配置

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

json 复制代码

{
  "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）。想精简工具集、省上下文，就把不需要的关掉：

json 复制代码

"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 / 无头环境（推荐给自动化流水线）

json 复制代码

{
  "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）：

bash 复制代码

# 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

然后：

json 复制代码

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

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

json 复制代码

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

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

json 复制代码

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

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

json 复制代码

{
  "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 编码助手真正"看见"浏览器

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

一、chrome-devtools-mcp 是什么？

一句话定义

三个官方主打特性

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

二、有什么用？

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

六个真正落地的使用场景

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

2. UI 改动的自证闭环

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

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

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

6. 内存泄漏排查

三、主流工具如何安装

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

四、参数配置

4.1 浏览器启动与连接

4.2 工具类别开关

4.3 实验性能力

4.4 隐私、安全与网络管控

4.5 截图与文件系统

4.6 四组常用配置模板

4.7 三种连接模式怎么选

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

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