cc_chrome_devtools_mcp_skill

Chrome DevTools 测试技能

概述

此技能通过 chrome-devtools-mcp 服务，使用 Chrome DevTools Protocol（CDP）实现自动化 Chrome 浏览器测试和性能分析。它提供 27 种专业级工具，可用于 Web 应用测试、性能测量、无障碍验证和浏览器自动化。

主要功能：

• 使用 Core Web Vitals（INP、LCP、CLS）进行性能分析
• 网络监控和 HAR 导出
• 无障碍树检查
• 响应式设计测试
• 浏览器自动化（填写表单、导航、交互）
• 多标签页和框架管理
• 设备和网络条件模拟

**浏览器支持：**仅支持 Chrome/Chromium（stable、beta、dev、canary 通道）

**Node.js 要求：**v20.19 或更高版本

快速开始

安装

# Add to Claude Code via CLI
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

# Verify installation
claude mcp list

基本配置

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--isolated=true",
        "--viewport=1920x1080"
      ]
    }
  }
}

重要说明

• 浏览器会在首次使用工具时自动启动（而非在连接 MCP 时启动）
• 为了安全，请使用 --isolated=true（会创建临时用户数据目录，并在使用后自动清理）
• 默认行为是在各会话间共享用户数据目录，且不会在两次运行之间清理
• 所有浏览器内容都会向 MCP 客户端公开，请避免使用敏感数据

当前 Core Web Vitals（截至 2024 年 3 月 12 日）

三项官方指标，按页面加载次数的第 75 百分位进行测量：

1. Interaction to Next Paint（INP）——于 2024 年 3 月 12 日取代 FID

   • 良好：≤ 200ms
   • 测量内容：输入延迟 + 处理时间 + 呈现延迟
   • 要求：真实用户交互（仅限字段数据）

2. Largest Contentful Paint（LCP）

   • 良好：≤ 2.5 秒
   • 测量内容：主要内容的加载性能

3. Cumulative Layout Shift（CLS）

   • 良好：≤ 0.1
   • 测量内容：视觉稳定性

**Total Blocking Time（TBT）**不是 Core Web Vital，而是用于衡量 INP 的实验室代理指标。

常见用例

1. 性能测试工作流

测量 Core Web Vitals 并分析性能瓶颈：

1. Start performance trace: performance_start_trace
2. Navigate to target URL: navigate_page
3. Wait for page load: wait_for
4. Stop trace and get metrics: performance_stop_trace
5. Analyze specific insights: performance_analyze_insight

采集的指标：

• INP（Interaction to Next Paint）
• LCP（Largest Contentful Paint）及其明细
• CLS（Cumulative Layout Shift）
• TBT（Total Blocking Time——实验室代理指标）
• 文档延迟分析

示例：

performance_start_trace with reload=true, autoStop=false
wait_for page to stabilize
performance_stop_trace
performance_analyze_insight with insightName="LCPBreakdown"

2. 网络监控和 HAR 导出

捕获所有 HTTP 请求和响应及其计时详情：

1. Navigate to URL: navigate_page
2. List all network requests: list_network_requests
3. Get specific request details: get_network_request

采集的数据：

• 标头、正文、Cookie
• 计时（DNS、连接、SSL、等待、接收）
• 资源类型（文档、样式表、图像、脚本、xhr、fetch）
• 安全详情（协议、密码套件）

**导出为 HAR：**使用 list_network_requests 生成 HTTP Archive v1.2 格式

筛选请求：

list_network_requests with resourceTypes=["xhr", "fetch", "document"]
list_network_requests with pageSize=50, pageIdx=0

3. 无障碍验证

检查无障碍树，验证是否符合 WCAG：

1. Navigate to page: navigate_page
2. Take accessibility snapshot: take_snapshot
3. Interact with elements using UIDs

快照提供：

• 唯一元素标识符（UID）
• 无障碍角色、名称和属性
• ARIA 属性和计算后的角色
• 屏幕阅读器兼容性分析
• 语义结构验证

示例工作流：

take_snapshot verbose=false (returns text-based a11y tree)
# Identify element UIDs from snapshot
click uid="element-123"
fill uid="input-456" value="test data"

4. 响应式设计测试

在不同设备和网络条件下进行测试：

1. Resize viewport: resize_page width=375 height=667
2. Emulate network: emulate_network throttlingOption="Slow 3G"
3. Emulate CPU: emulate_cpu throttlingRate=4
4. Take screenshot: take_screenshot fullPage=true

设备模拟选项：

• 视口尺寸和设备缩放系数
• 网络条件：离线、Slow 3G、Fast 3G、Slow 4G、Fast 4G
• CPU 限速：减速 1–20 倍
• 支持最大触控点数的触摸模拟

**屏幕截图格式：**PNG、JPEG、WebP（可设置质量）

5. 浏览器自动化

自动填写表单、导航和交互：

1. Take snapshot to get element UIDs: take_snapshot
2. Fill form fields: fill_form elements=[{uid, value}, ...]
3. Click buttons: click uid="submit-button"
4. Handle dialogs: handle_dialog action="accept"
5. Wait for results: wait_for text="Success"

交互工具：

• click（单击/双击）
• fill（输入字段、文本区域、选择框）
• fill_form（一次填写多个字段）
• hover（鼠标悬停）
• drag（拖放）
• upload_file（文件输入）
• handle_dialog（警告、确认、提示）

导航工具：

• navigate_page（URL、重新加载）
• navigate_page_history（后退/前进）
• wait_for（等待文本出现或满足条件）

6. 多标签页管理

同时处理多个页面和框架：

1. List open pages: list_pages
2. Create new page: new_page url="https://example.com"
3. Switch context: select_page pageIdx=1
4. Close pages: close_page pageIdx=2

框架处理：

• 自动连接到子框架和工作线程
• 检查框架树结构
• 导航期间保持会话

高级工作流

通过设备模拟进行性能分析

1. resize_page width=390 height=844 (iPhone 14 Pro)
2. emulate_network throttlingOption="Fast 4G"
3. emulate_cpu throttlingRate=4
4. performance_start_trace reload=true
5. performance_stop_trace
6. performance_analyze_insight insightName="DocumentLatency"

通过筛选进行网络分析

1. navigate_page url="https://example.com"
2. list_network_requests resourceTypes=["script", "fetch", "xhr"]
3. Filter by: pageSize=100, pageIdx=0, includePreservedRequests=true
4. get_network_request reqid=123 (detailed timing/headers/body)

无障碍测试模式

1. navigate_page url="https://example.com"
2. take_snapshot verbose=true (full a11y tree with all properties)
3. Validate: roles, names, ARIA attributes, relationships
4. Test interactions: click, fill, keyboard navigation via UIDs

跨浏览器视口测试

1. Define breakpoints: [320, 768, 1024, 1920]
2. For each breakpoint:
   - resize_page width=X height=Y
   - take_screenshot format="png" quality=90
   - take_snapshot (verify accessibility)
3. Compare layouts and a11y across sizes

完整工具参考

6 个类别中共有 27 个工具：

输入自动化（8）： click、drag、fill、fill_form、handle_dialog、hover、press_key、upload_file

导航（7）： close_page、list_pages、navigate_page、navigate_page_history、new_page、select_page、wait_for

模拟（3）： emulate_cpu、emulate_network、resize_page

性能（3）： performance_analyze_insight、performance_start_trace、performance_stop_trace

网络（2）： get_network_request、list_network_requests

调试（4）： evaluate_script、get_console_message、list_console_messages、take_screenshot、take_snapshot

如需详细的工具参数和示例，请参阅 TOOLS.md

如需完整的工作流模式，请参阅 WORKFLOWS.md

如需了解 Core Web Vitals 阈值和测量指南，请参阅 METRICS.md

配置选项

连接标志

• --browserUrl, -u <string> - 连接到正在运行的 Chrome 实例（端口转发）
• --wsEndpoint, -w <string> - Chrome 连接的 WebSocket 端点
• --wsHeaders <JSON> - 用于经过身份验证的 WebSocket 连接的自定义标头

浏览器配置

• --headless <boolean> - 以无头模式运行（默认：false）
• --executablePath, -e <string> - 自定义 Chrome 可执行文件的路径
• --channel <string> - Chrome 通道：stable、canary、beta、dev（默认：stable）
• --viewport <string> - 初始视口大小（格式：WIDTHxHEIGHT，例如 1280x720）

安全与隔离

• --isolated <boolean> - **推荐：**创建临时 user-data-dir，并自动清理（默认：false）
• --user-data-dir <string> - 自定义用户数据目录
• --acceptInsecureCerts <boolean> - 忽略证书错误（安全风险——仅用于开发/测试）

网络

• --proxyServer <string> - 代理服务配置

调试

• --logFile <string> - 调试日志的路径（设置 DEBUG=* 环境变量以输出详细日志）

其他

• --chromeArg <string> - 其他 Chrome 参数（可重复指定）

查看所有选项：npx chrome-devtools-mcp@latest --help

生产环境配置示例

安全的隔离测试

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

连接到外部 Chrome 实例

# Launch Chrome with remote debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

# Get WebSocket endpoint
curl http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl'

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>"
      ]
    }
  }
}

配置生产环境日志

{
  "mcpServers": {
    "chrome-devtools-prod": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222",
        "--isolated=true",
        "--logFile=/var/log/chrome-devtools-mcp.log"
      ],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

安全注意事项

数据暴露警告

Chrome DevTools MCP 官方安全声明：

“chrome-devtools-mcp 会向 MCP 客户端公开浏览器实例的内容，使其能够检查、调试和修改浏览器或 DevTools 中的任何数据。请勿分享不希望 MCP 客户端看到的敏感或个人信息。”

最佳实践

1. 在敏感工作流中使用隔离模式

   • --isolated=true 会创建临时用户数据目录
   • 浏览器关闭后自动清理
   • 防止会话之间的数据持久化

2. 谨慎处理证书

   • --acceptInsecureCerts 存在安全风险
   • 仅用于开发/测试环境
   • 切勿用于敏感数据

3. 管理用户数据目录

   • 默认目录由所有实例共享
   • 运行之间不会清除
   • 包含 Cookie、缓存和浏览历史记录
   • 使用 --isolated 或自定义 --user-data-dir 进行管理

4. WebSocket 身份验证

   • 使用 --wsHeaders 进行身份验证连接
   • 示例：--wsHeaders='{"Authorization":"Bearer token"}'
   • 仅适用于 --wsEndpoint

技术限制

已验证的限制

1. 浏览器支持： 仅支持 Chrome/Chromium（不支持 Firefox、Safari 和旧版 Edge）

2. Node.js 要求： v20.19 或更高版本（最新维护版 LTS）

3. 浏览器生命周期： 首次使用工具时浏览器会自动启动，而非在 MCP 服务连接时启动

4. 默认持久化： 除非使用 --isolated=true，否则用户数据目录会在多次运行之间保留

5. 权限要求：

   • 某些 MCP 客户端可能需要 macOS“完全磁盘访问”权限
   • Chrome 需要获得创建自身沙盒的权限
   • 可能需要停用 MCP 客户端沙盒，或使用外部 Chrome 实例

6. 截图格式： 初始捕获时使用指定格式（JPEG/PNG），最终输出使用 WebP，失败时回退到 PNG

7. 工具可用性： 连接后即可使用全部 27 个工具；不会逐步解锁

资源和文档

官方来源

• GitHub 仓库： https://github.com/ChromeDevTools/chrome-devtools-mcp
• npm 包： https://www.npmjs.com/package/chrome-devtools-mcp
• Chrome DevTools Protocol： https://chromedevtools.github.io/devtools-protocol/

Core Web Vitals

• Web Vitals 概览： https://web.dev/articles/vitals
• INP 文档： https://web.dev/articles/inp
• LCP 文档： https://web.dev/articles/lcp
• CLS 文档： https://web.dev/articles/cls
• INP 取代 FID（3 月 12 日）： https://web.dev/blog/inp-cwv-march-12

工具

• PageSpeed Insights： https://pagespeed.web.dev
• Chrome 用户体验报告： https://developer.chrome.com/docs/crux
• Lighthouse 文档： https://developer.chrome.com/docs/lighthouse

相关技能文件

• WORKFLOWS.md - 详细的工作流模式和多步骤流程
• METRICS.md - 完整的 Core Web Vitals 阈值和测量指南
• TOOLS.md - 全面的工具参数参考和示例

版本信息

• MCP 服务版本： v0.5.1（2025 年 10 月 17 日）
• 工具数量： 27 个工具
• Core Web Vitals 更新： INP 于 2024 年 3 月 12 日取代 FID
• 当前指标： INP、LCP、CLS（TBT 是实验室代理指标，并非 Core Web Vital）