website-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Website Debugging Skill

网站调试技能

Lightweight, token-efficient browser debugging toolkit for frontend development. Uses CLI scripts instead of MCP servers to minimize context usage (~300 tokens vs 13k-18k).

一款轻量、低Token消耗的前端开发浏览器调试工具包。使用CLI脚本而非MCP服务器，将上下文使用量降至最低（约300 Token，对比传统方案的13k-18k Token）。

Quick Start

快速开始

Use the slash commands for easiest access:

```
/debug-page <url>
```
- Start debugging session
```
/screenshot
```
- Take screenshot
```
/pick-element
```
- Interactive element selection
```
/test-responsive
```
- Test at all breakpoints
```
/verify-changes
```
- Verify after making changes

使用斜杠命令可最便捷地访问功能：

```
/debug-page <url>
```
- 启动调试会话
```
/screenshot
```
- 截取屏幕截图
```
/pick-element
```
- 交互式元素选择
```
/test-responsive
```
- 测试所有断点
```
/verify-changes
```
- 变更后进行验证

Or use scripts directly:

或直接使用脚本：

bash

undefined

bash

undefined

Start browser

启动浏览器

node scripts/browser-start.js node scripts/browser-start.js --profile # Preserve logins node scripts/browser-start.js --webkit # Safari/WebKit

node scripts/browser-start.js node scripts/browser-start.js --profile # 保留登录状态 node scripts/browser-start.js --webkit # Safari/WebKit模式

Navigate

导航页面

node scripts/browser-nav.js https://localhost:3000

Debug

调试操作

node scripts/browser-screenshot.js node scripts/browser-eval.js 'document.title' node scripts/browser-pick.js "Select element" node scripts/browser-console.js --errors node scripts/browser-network.js --failures

undefined

undefined

Core Tools Reference

核心工具参考

Script	Purpose	Output
`browser-start.js`	Launch Chrome/WebKit with debug port	Status message
`browser-nav.js <url>`	Navigate to URL	Confirmation
`browser-screenshot.js`	Capture viewport	File path (PNG)
`browser-eval.js '<js>'`	Run JS in page	Result or error
`browser-pick.js "<msg>"`	Interactive selector	CSS selectors
`browser-console.js`	Get console output	Logs/errors
`browser-network.js`	Network activity	Request/response data
`browser-dom.js "<sel>"`	Get DOM snapshot	HTML fragment
`browser-close.js`	Close browser	Confirmation

脚本	用途	输出
`browser-start.js`	启动带调试端口的Chrome/WebKit浏览器	状态消息
`browser-nav.js <url>`	导航至指定URL	确认信息
`browser-screenshot.js`	捕获视口截图	文件路径（PNG格式）
`browser-eval.js '<js>'`	在页面中运行JavaScript代码	执行结果或错误信息
`browser-pick.js "<msg>"`	交互式选择元素	CSS选择器
`browser-console.js`	获取控制台输出	日志/错误信息
`browser-network.js`	查看网络活动	请求/响应数据
`browser-dom.js "<sel>"`	获取DOM快照	HTML片段
`browser-close.js`	关闭浏览器	确认信息

Self-Debugging Workflow

自调试工作流

When debugging frontend code Claude has written or modified:

当调试Claude编写或修改的前端代码时：

1. Visual Verification Loop

1. 视觉验证循环

bash

undefined

bash

undefined

After making CSS/HTML changes, verify visually

完成CSS/HTML变更后，进行视觉验证

node scripts/browser-screenshot.js

Claude reads the screenshot, identifies issues, iterates

Claude读取截图，识别问题并迭代优化

undefined

undefined

2. Console Error Detection

2. 控制台错误检测

bash

undefined

bash

undefined

Check for JavaScript errors after changes

变更后检查JavaScript错误

node scripts/browser-console.js --errors

Fix any errors found, re-verify

修复发现的错误，重新验证

undefined

undefined

3. Responsive Testing

3. 响应式测试

bash

undefined

bash

undefined

Test at different viewport sizes

在不同视口尺寸下测试

node scripts/browser-resize.js 375 667 # iPhone SE node scripts/browser-screenshot.js node scripts/browser-resize.js 768 1024 # iPad node scripts/browser-screenshot.js node scripts/browser-resize.js 1920 1080 # Desktop node scripts/browser-screenshot.js

undefined

node scripts/browser-resize.js 375 667 # iPhone SE尺寸 node scripts/browser-screenshot.js node scripts/browser-resize.js 768 1024 # iPad尺寸 node scripts/browser-screenshot.js node scripts/browser-resize.js 1920 1080 # 桌面端尺寸 node scripts/browser-screenshot.js

undefined

4. Element Inspection

4. 元素检查

bash

undefined

bash

undefined

When user reports "X looks wrong", have them select it

当用户反馈“X显示异常”时，让用户选择对应元素

node scripts/browser-pick.js "Click on the element that looks wrong"

node scripts/browser-pick.js "点击显示异常的元素"

Returns detailed info including computed styles

返回包含计算样式在内的详细信息

undefined

undefined

Browser Engine Selection

浏览器引擎选择

Chrome (Default)

Chrome（默认）

Primary engine. Uses Chrome DevTools Protocol on port 9222.

Best debugging experience
Full DevTools compatibility
Use
```
--profile
```
to preserve logins

首选引擎。使用端口9222上的Chrome DevTools Protocol。

最佳调试体验
完整的DevTools兼容性
使用
```
--profile
```
参数保留登录状态

WebKit/Safari

Fallback via Playwright's WebKit build. Closest to Safari behavior on macOS.

bash

node scripts/browser-start.js --webkit

Use for Safari-specific testing
Layout verification
WebKit-specific bugs

通过Playwright的WebKit构建版本作为备选方案，最接近macOS上的Safari行为。

bash

node scripts/browser-start.js --webkit

用于Safari专属测试
布局验证
WebKit专属Bug排查

When to Use Each

引擎选择场景

Scenario	Engine
General debugging	Chrome
Safari layout issues	WebKit
Testing with logins	Chrome `--profile`
Cross-browser comparison	Both
CI/headless testing	Chrome or WebKit

场景	推荐引擎
通用调试	Chrome
Safari布局问题	WebKit
带登录状态的测试	Chrome `--profile`
跨浏览器对比	两者皆可
CI/无头测试	Chrome或WebKit

Advanced Usage

高级用法

Detailed Documentation

详细文档

For complex scenarios, load the appropriate reference:

CSS Debugging: See references/css-debug.md
JavaScript Errors: See references/js-debug.md
Self-Debugging: See references/self-debug.md

针对复杂场景，可查阅对应参考文档：

CSS调试：查看 references/css-debug.md
JavaScript错误：查看 references/js-debug.md
自调试：查看 references/self-debug.md

Composable Output

可组合输出

All scripts output to files when practical, enabling:

bash

undefined

所有脚本会在可行时将结果输出到文件，支持以下操作：

bash

undefined

Capture multiple screenshots for comparison

捕获多张截图用于对比

node scripts/browser-screenshot.js --output=/tmp/before.png

... make changes ...

... 进行变更 ...

node scripts/browser-screenshot.js --output=/tmp/after.png

Save DOM snapshot for analysis

保存DOM快照用于分析

node scripts/browser-dom.js "body" > /tmp/page-structure.html

Export console log for review

导出控制台日志用于审阅

node scripts/browser-console.js > /tmp/console-log.txt

undefined

node scripts/browser-console.js > /tmp/console-log.txt

undefined

Chaining Commands

命令链式调用

bash

undefined

bash

undefined

Navigate and screenshot in one command

一键完成导航和截图

node scripts/browser-nav.js https://example.com && node scripts/browser-screenshot.js

Full page audit

完整页面审计

node scripts/browser-nav.js $URL &&
node scripts/browser-console.js --errors > /tmp/errors.txt &&
node scripts/browser-screenshot.js

undefined

node scripts/browser-nav.js $URL &&
node scripts/browser-console.js --errors > /tmp/errors.txt &&
node scripts/browser-screenshot.js

undefined

Setup Requirements

环境配置要求

Chrome

Chrome must be launchable from command line. The start script handles this automatically.

需支持从命令行启动Chrome，启动脚本会自动处理该操作。

WebKit (Optional)

WebKit（可选）

For Safari testing, ensure Playwright is installed:

bash

npm install -g playwright
npx playwright install webkit

如需进行Safari测试，请确保已安装Playwright：

bash

npm install -g playwright
npx playwright install webkit

Dependencies

依赖项

Scripts require Node.js and puppeteer-core:

bash

npm install -g puppeteer-core

脚本需要Node.js和puppeteer-core：

bash

npm install -g puppeteer-core

Troubleshooting

故障排除

"Cannot connect to browser"

“无法连接到浏览器”

Browser may not be running or wrong port:

bash

node scripts/browser-start.js  # Restart browser

浏览器可能未运行或端口错误：

bash

node scripts/browser-start.js  # 重启浏览器

"Permission denied"

“权限被拒绝”

Scripts may need execute permission:

bash

chmod +x ./scripts/*.js

脚本可能需要执行权限：

bash

chmod +x ./scripts/*.js

Chrome already running

Chrome已在运行

Kill existing instances first:

bash

killall "Google Chrome" 2>/dev/null
node scripts/browser-start.js

先终止现有实例：

bash

killall "Google Chrome" 2>/dev/null
node scripts/browser-start.js

WebKit not found

未找到WebKit

Install Playwright browsers:

bash

npx playwright install webkit

安装Playwright浏览器：

bash

npx playwright install webkit