fe-auto-test —— Playwright 浏览器验证 + Lighthouse 全维度体检

定位

用 Playwright 真实浏览器验证前端行为：控制台报错、Vue 挂载、Canvas / Three.js / WebGL 渲染、UI 交互、截图。和静态读代码不同，它能拿到 JS 执行后的真实 DOM 与运行时错误。页面正常打开后，还会默认用 Lighthouse 跑一次全维度体检（性能 / 无障碍 / 最佳实践 / SEO + 缓存压缩实测 + 资源拆解），产出按收益排序的优化建议。

何时用 / 何时不用

用：需要看「运行时真实表现」——白屏排查、组件挂没挂上、three.js/canvas 有没有画出来、有没有 console error、交互点击后状态对不对、视觉截图；以及需要量化性能 / 无障碍 / 最佳实践 / SEO 评分并给优化建议。

对话里说「验证下页面」「看看渲染对不对」「页面白屏排查」「跑下 lighthouse」「这页性能怎么样」「LCP / TBT / Core Web Vitals」「首屏太慢」「做容错测试」「每个路由都看下」等都会触发。

不用：编译错误、类型错误、纯逻辑 bug、能靠读代码 / grep / lint 定位的问题。启动真实浏览器有成本，确实需要真实渲染时才用。

三个本机前提（不懂会踩）

依赖可能没装：本 skill 依赖 playwright / lighthouse。别假定它们在——闭环第一步会自动检查并补装。
dev 端口不固定：Vite 端口被占会自动 +1（5173→5174…），所以禁止硬编码端口，必须先跑探测脚本拿实际端口。
产物统一落中央目录（$FE_TEST_OUTPUT_DIR，未设则 $HOME/.claude/playwright）：截图必须传绝对路径（~ 不会被 MCP 展开），否则会落到家目录而清理脚本扫不到。

两条路：MCP 路径 vs 脚本路径

本 skill 每项能力都有两种实现，能力等价，区别只在依赖：

	MCP 路径	脚本路径
渲染 / console / 截图 / 交互	`browser_*`（playwright 插件）	`route-audit.mjs`、`resilience-audit.mjs` 等
全维度体检	lighthouse MCP 的 7 个工具	`lighthouse-audit.mjs`（一条命令跑完全部）
依赖	MCP 注册 + 重启会话才生效	只要 npm 包 + chromium，装完立即可用

关键认知：CC 的 MCP 新注册后当前会话拿不到工具，必须重启。所以依赖缺失时不会停下来让你重启——skill 自动补装 npm 包并走脚本路径把活干完，同时把 MCP 注册好留给下次会话。

标准闭环

skill 内部封装了完整闭环，你只要提需求，它会自动跑：

依赖检查 + 自动补装（每次第一件事）
```
bash ${CLAUDE_PLUGIN_ROOT}/skills/fe-auto-test/scripts/check-deps.sh
```
缺 playwright / chromium / lighthouse 自动装；末尾两个标记 PW_READY / LH_READY 决定各自走 MCP 路径还是脚本路径。想只诊断不装加 --no-install。
探测 / 启动 dev server（仅本地项目）：check-server.sh 读 vite.config.* 的 server.port，或扫常见端口，打印实际端口。给了完整线上 URL 时跳过这步。
浏览器打开页面：browser_navigate + browser_snapshot，白屏会一眼看出。
检查控制台报错：browser_console_messages，重点看 error/warning，并排除良性噪声（音视频 play/pause 竞态、ResizeObserver loop、第三方脚本 404 等）。
全维度页面体检（默认执行，不用等你说「跑性能」）：五块——性能首屏 / 无障碍 / 最佳实践 / SEO / 缓存压缩实测 / 资源按域名大小拆解。
按需做针对性检查（three.js / 组件挂载 / 交互 / 容错全站）。
截图（必须绝对路径，文件名 test-{描述}.png）。
清理临时截图 cleanup-screenshots.sh。
收尾：browser_close，若 dev server 是它为验证起的就 close-server.sh <端口> 关掉。

全维度体检产出

LH_READY=0 走脚本路径（推荐，一条命令跑完全部）：

node ${CLAUDE_PLUGIN_ROOT}/skills/fe-auto-test/scripts/lighthouse-audit.mjs <url> \
  --device=mobile --resources=/tmp/res.json
python3 ${CLAUDE_PLUGIN_ROOT}/skills/fe-auto-test/scripts/resource-report.py /tmp/res.json

一次输出：四维评分（性能 / 无障碍 / 最佳实践 / SEO）+ 六项指标（FCP / LCP / TBT / CLS / SI / TTI，带分档）+ 未用 JS + 未用 CSS + 无障碍硬失败项。它直接 import lighthouse 库、不经 MCP，装完即用，且 localhost→127.0.0.1、anti-debug 陷阱等坑都在脚本里处理了。

resource-report.py 会按 type / 域名（自有 vs 第三方）/ 大小拆解资源，检测 legacy 包被现代浏览器误下载、非 webp 大图，并对最大的静态资源实测 Cache-Control 与 Content-Encoding（gzip vs brotli）——探针走 node 直连，不用 curl（curl 会被本机 hook 拦）。

判读要点：综合分低但 FCP/LCP 绿 → 瓶颈在 TBT（主线程被 JS 阻塞），重心是减首屏 JS；LCP 慢 → 大图没预加载 / 被阻塞；CLS 高 → 没占位导致布局抖动；带 hash 静态产物应上一年长缓存 max-age=31536000, immutable，HTML 入口走短缓存以便发版即时生效。

容错 / 边界 / 全站批量测试

用户点名「各种容错测试」「每个路由都看看」「清缓存 / 清 LocalStorage / 登录态 / CDN」时，MCP 一页页点太慢，改用 bundled 的 Playwright 编程式脚本（参数化，传 baseURL）：

脚本	干什么
`http-headers.mjs`	CDN / 缓存 / 压缩 / SSR 冷启动 TTFB（`--cold` 绕边缘缓存测回源）
`route-audit.mjs`	逐路由抽样审计（渲染 + console + SEO meta）
`ssr-status-sweep.mjs`	全站 SSR 状态清扫，专抓致命 500（抽样会漏，要全量必跑它）
`resilience-audit.mjs`	5 个容错场景：清空存储 reload、注入脏存储、未登录访问受保护路由、Hydration mismatch 检测

SSR 500 最高频根因：CJS 包（gifenc/fflate 等）被静态 import 进路由 chunk，SSR 外部化后 Node 按 ESM 加载 CJS 报 does not provide an export named 'X'。修法：加进 vite.config.ts 的 ssr.noExternal，或组件内改 await import() 懒加载。

几条调试配方

检查 three.js / WebGL：browser_evaluate 取 canvas.getContext('webgl2')、glError、drawingBuffer——canvasSize 含 0 说明尺寸塌陷（父容器没高度）。
检查 Vue 挂载：读 #app 的 children.length，false + console error 多半是渲染期抛错整树没挂上。
带动画元素 click 超时：CTA 按钮的呼吸 / 缩放动画会让 Playwright 永远等不到 stable → TimeoutError。这不是 bug，改用 browser_evaluate 直接派发 click() 并断言副作用。
anti-debug 陷阱：页面有 debugger 陷阱会拦 Lighthouse（全指标 N/A）。找站点的 debug 后门参数（如 ?debug=true）绕过，或降级用 Playwright 读 performance API（不开 Debugger 域，不触发陷阱）。

fe-auto-test 浏览器验证与体检

定位