init-playwright

在 pnpm monorepo 初始化 Playwright 工具链

本技能记录在 Vue 3 + Vite + TypeScript pnpm monorepo 中初始化 Playwright 三件套的完整工作流，及执行中发现的 2 个关键环境坑。

适用场景

• pnpm monorepo 项目首次接入 Playwright
• 大屏/可视化项目需要视觉回归测试
• 需要为 AI agent 配备浏览器驱动能力（MCP + CLI skills）
• Node 22 + Windows 环境（坑与 Node 版本/OS 相关）

⚠️ 无头浏览器 CPU 风险须知（重要）

headless（无头）≠ 轻量。无头 Chromium 仍然运行完整的浏览器引擎（Blink 排版、V8 JS 执行、WebGL/WebGPU 渲染管线），只是不显示窗口。在 大屏 3D/可视化项目 下，headless 模式的 CPU/GPU 消耗与 headed（有头）几乎无异：

因此，使用本技能初始化的项目，必须阅读并遵循「无头浏览器安全使用规范」章节的约束。尤其在大屏/可视化/3D 密集型项目上，优先使用 pwvisual（headed）驱动浏览器，避免让 pwcore（headless）长时间常驻。

工作流总览

装三件套 → 端口固定 → 写根级 playwright.config.ts
    → visual-stability.css → .mcp.json + MCP 配置
    → playwright-cli + AI skills 生成
    → package.json scripts (test:e2e + ci)
    → e2e 冒烟测试 → 视觉基线测试
    → AI 记忆三处更新 → 验收

步骤 1：安装三件套

pnpm add -D -w @playwright/test @playwright/cli playwright-mcp
pnpm exec playwright install chromium
pnpm exec playwright --version  # 验证

三件套职责：

步骤 2：monorepo 子 app dev server 端口固定

每个需要测试的 app 的 vite.config.ts 显式设端口，避免 playwright webServer 端口冲突：

server: {
  port: 5174,          // 一期用 5173，二期用 5174，依此类推
  host: "127.0.0.1",   // 必须 127.0.0.1，不用 0.0.0.0
},

步骤 3：根级 playwright.config.ts

monorepo 推荐根目录单一配置，用 testDir + testMatch 集中管理，projects 区分不同 app（后续扩展）：

import { defineConfig, devices } from "@playwright/test";

const CI = !!process.env.CI;
const baseURL = "http://127.0.0.1:5174";

export default defineConfig({
	testDir: "./tests",
	testMatch: "**/*.spec.ts", // isolate from vitest *.test.ts
	outputDir: "artifacts/test-results",
	expect: {
		toHaveScreenshot: { maxDiffPixelRatio: 0.001 },
	},
	fullyParallel: false, // 大屏 3D 资源，并行争抢 GPU
	workers: 1,
	retries: CI ? 2 : 0,
	reporter: [["list"], ["html", { open: "never", outputFolder: "artifacts/playwright-report" }]],
	use: {
		baseURL,
		/** 显式声明 headless，不依赖默认值——确保 CI 和非 CI 行为一致 */
		headless: true,
		/** 禁用 GPU 及相关加速，降低 headless 模式下的 CPU 消耗 */
		launchOptions: {
			args: ["--disable-gpu", "--disable-software-rasterizer", "--disable-dev-shm-usage", "--no-sandbox"],
		},
		timezoneId: "Asia/Shanghai", // 中国大屏用上海时区
		viewport: { width: 1440, height: 900 },
		stylePath: "tests/visual/visual-stability.css",
		screenshot: "only-on-failure",
		trace: "retain-on-failure",
	},
	snapshotPathTemplate: "tests/visual/__screenshots__/{testFilePath}/{arg}{ext}",
	projects: [{ name: "chromium-desktop", use: { ...devices["Desktop Chrome"] } }],
	webServer: {
		command: "pnpm --filter <pkg-name> dev", // 见坑 #2
		url: baseURL,
		reuseExistingServer: !CI,
		timeout: 120_000,
	},
});

坑 #1：lint-staged prettier --experimental-cli 在 Node 22 崩溃

现象：lint-staged.config.js 里 "*": "prettier --experimental-cli --write" 在 Node 22 沙箱环境触发 WorkTankWorkerError: Terminated，阻塞所有 git commit。

根因：prettier 3.8.1 的 --experimental-cli 依赖 worktank worker 池，在部分 Node 22 环境不稳定。

修复：

// lint-staged.config.js
export default {
	/**
	 * 临时去掉 prettier 的 --experimental-cli 标志。
	 * prettier 3.8.1 的 --experimental-cli worktank worker
	 * 在 Node 22 沙箱崩溃，回退到普通 --write，待上游修复后恢复。
	 *
	 * 另加 --ignore-unknown：跳过无 parser 的文件（如 .gitignore）
	 */
	"*": "prettier --write --ignore-unknown",
};

注意：--ignore-unknown 很重要——不加的话 .gitignore 等无 parser 文件也会被 prettier 报错阻塞提交。

坑 #2：playwright webServer 的 pnpm filter 吞掉 --host

现象：playwright.config.ts 的 webServer.command 设为 pnpm dev:<app> --host 127.0.0.1，webServer 自动启动后返回 404。CI 模式下 reuseExistingServer: false 会直接失败。

根因：pnpm dev:<app> 展开为 pnpm --filter <pkg> dev，后面的 --host 127.0.0.1 被 pnpm filter 吞掉，没有传给 vite。

修复：不在 webServer.command 里传 --host/--port，依赖 vite.config.ts 已有的 server 配置：

// playwright.config.ts
webServer: {
  // 不在命令行传 --host/--port，依赖 vite.config.ts 的 server 配置
  command: "pnpm --filter <pkg> dev",
  url: baseURL,
  reuseExistingServer: !CI,
  timeout: 120_000,
},

通用原则：vite 项目的 playwright webServer 所有 server 参数放 vite.config.ts，命令行只传 `dev`。

步骤 4：vitest 与 playwright 命名隔离

两套配置天然隔离（vitest include 用 *.test.ts，playwright testMatch 用 *.spec.ts），无需互相 exclude。

步骤 5：基线截图提交策略

• 基线截图提交到 tests/visual/__screenshots__/（不进 .gitignore）
• artifacts/、test-results/、playwright-report/ 忽略
• 首次跑 --update-snapshots 生成基线，二次跑 pnpm test:e2e 验证

⚠️ 无头浏览器安全使用规范

核心原则

headless Chromium 不是轻量模式，它在后台运行完整的浏览器引擎。以下规范帮助你在项目中安全使用 Playwright，避免 CPU 过载事故。

① 优先选择 headed 模式驱动浏览器

不是所有场景都适合 headless。按优先级选择：

② MCP 浏览器进程是持久化的，必须管理生命周期

pw_core 和 pw_visual 通过 MCP 协议挂载，AI agent 启动后浏览器进程持续存活。不会自动关闭。

• 会话结束时：必须手动关闭浏览器。在 AI agent 退出前执行：

  // 通过 pw_core 或 pw_visual 的 evaluate_script 关闭页面
  await page.close();
  // 或在测试脚本中使用 afterAll 钩子

• 长时间不使用：建议在 .mcp.json 中配置进程超时或定期重启
• 监控 CPU：大屏项目建议在 AI agent 使用浏览器后检查任务管理器，确认 Chromium 进程已退出

③ 大屏 3D 项目的特殊注意事项

如果你的项目包含 ECharts WebGL/3D 图表（如 Ring3DChart、3D 地图等），headless 模式的 CPU 消耗会显著高于纯 2D 页面：

• 不要频繁截图：每次 get-screenshot 都会触发完整的 WebGL 帧渲染，CPU 飙升至 100%
• 使用 pw_visual＞pw_core：headed 模式至少让你能观察到浏览器的运行状态
• 减少无意义的页面访问：AI agent 应避免在 headless 下反复 "看一眼" 大屏页面
• 考虑降低截图分辨率：在非必要场景下调小 viewport 或截图分辨率

④ 在 agent-progress.md 或 AI 记忆中加入浏览器进程回收提醒

建议在项目的 AI 记忆文件中加入以下约束规则：

### Playwright 浏览器进程使用规则（CPU 安全）

- AI 驱动浏览器默认使用 pw_visual（headed），仅 token 敏感场景用 pw_core
- 每次使用浏览器后检查任务管理器，确认 Chromium 进程已退出
- 禁止在 headless 模式下对 3D 大屏页面做高频截图（每 10 秒 1 次以上）
- 大屏 3D 页面优先用 pw_visual 驱动，避免无头模式下的 GPU 空转

⑤ 在 session 结束时执行进程清理

AI 会话结束时，建议执行以下命令确认没有残留 Chromium 进程：

# Windows - 检查遗留的 Chromium 进程
tasklist /FI "IMAGENAME eq chrome.exe" 2>NUL | find /I /N "chrome.exe"
# 可选：强制关闭残留（请先确认无其他用户进程）
# taskkill /F /IM chrome.exe 2>NUL

# Linux/macOS
# ps aux | grep -i chromium | grep -v grep
# killall chromium  # 谨慎使用

📋 真实事故复盘：无头浏览器 CPU 过载

以下是一次真实事故的完整记录。该事故直接导致 Playwright 工具链从项目中被全面删除。记录于此，帮助后续使用者识别同类型风险。

事故时间线

根因分析

初始化 Playwright（pw_core headless MCP）
  ↓ AI agent 在 3 天内反复通过 pw_core 驱动浏览器 "查看" 大屏 3D 页面
  ↓ headless Chromium 在后台完整执行 WebGL 渲染管线（3D 环形图、3D 地图等）
  ↓ 每次 get-screenshot / get-full-snapshot 都触发完整的 GPU 帧渲染
  ↓ MCP 协议下浏览器是长连接进程，不会用完即销毁
  ↓ 浏览器进程连续运行 3 天 → 内存持续增长 → CPU 100%
  ↓ 主机性能严重下降，用户被迫删除 Playwright

关键教训

1. MCP 浏览器是长连接，不是一次性调用 — 它会在整个 AI 会话期间存活，用完不自动关闭。这是与 pnpm test:e2e 一次性测试的最大区别。
2. headless 不省 CPU — headless 屏蔽的是窗口，不是渲染管线。大屏 3D 项目下 headless 和 headed 的 GPU 负载几乎一样。
3. 3 天内就能酿成事故 — 从初始化到全面删除只有 3 天时间周期。一旦 AI agent 开始频繁调用浏览器，CPU 问题会快速恶化。
4. 习惯性 "看一眼" 是最危险的用法 — AI agent 天然倾向于频繁截图/快照来确认页面状态，在 headless 模式下这种 "看一眼" 习惯会触发大量无用 GPU 渲染。

预防措施

• 初始化时就确认：你的项目是 3D 大屏类吗？如果是，立即改用 pwvisual（headed）而非 pwcore
• 使用前先设规则：在 AGENTS.md 中明确约束浏览器调用频率和方式（参考"AI 记忆更新模板"中的安全规则）
• 使用后立即检查：每个 AI 会话结束时运行 tasklist 检查是否有残留 Chromium 进程
• 避免长时间无人值守：headless 浏览器不要长时间挂机。如果必须使用，建议设置定时重启或进程超时

🧰 故障排查指南

如果你在使用 Playwright 过程中遇到以下现象，说明可能正在重演上述事故。

症状速查表

紧急止损步骤

如果发现 CPU 已经异常飙升：

# 步骤 1：立即检查 Chromium 进程数
tasklist /FI "IMAGENAME eq chrome.exe" 2>NUL

# 步骤 2：如果存在大量 Chromium 进程，强制关闭
taskkill /F /IM chrome.exe 2>NUL

# 步骤 3：关闭重开 AI 会话，确认浏览器工具已不在会话中
# 步骤 4：检查 .mcp.json，临时移除 pw_core/pw_visual 条目
# 步骤 5：复盘分析 — 是哪个 AI agent 行为触发了高频调用

长期回归检查清单

每次 Playwright 使用后，复查以下项目：

• [ ] tasklist 中无残留 chrome.exe
• [ ] 任务管理器 CPU 占用率回归正常水平
• [ ] AI 会话日志中无异常密集的浏览器调用记录
• [ ] 各 app 的 vite dev server 已正常关闭
• [ ] 如果是 CI 环境，检查 CI 日志中 Chromium 进程退出状态码

AI 记忆更新模板

在 CLAUDE.md / AGENTS.md / GEMINI.md 三处插入（<300 字）：

## Playwright 工具链

三件套职责：@playwright/test (CI 固化） | @playwright/cli （生成 skills) | playwright-mcp (AI 驱动浏览器）

命名：vitest→*.test.ts，playwright→*.spec.ts

⚠️ 浏览器进程安全规则：

- AI 驱动浏览器默认用 pw_visual（headed），仅 token 敏感场景用 pw_core
- 每次使用浏览器后检查任务管理器，确保 Chromium 进程已退出
- 禁止在 headless 模式下对 3D 大屏页面做高频截图
- 大屏 3D 页面优先用 pw_visual 驱动，避免无头模式 GPU 空转

规则：视觉对齐后必须用 @playwright/test 固化。

环境注意

• Node 22 + Windows：所有 node/pnpm 命令加 NODE_OPTIONS= 前缀（清空有问题的 NODE_OPTIONS=--use-system-ca）
• git commit：必须用 git-commit 技能（查远程 commit-types.ts emoji + commitlint 预校验 + -F 文件方式）
• pre-commit hook：修改 lint-staged.config.js 后验证一次 commit 能通过

验收清单

1. pnpm install 无报错
2. pnpm exec playwright --version 输出版本号
3. pnpm test:e2e 3 个测试全 pass（smoke + visual）
4. pnpm run ci 全流程通过（vitest → build → test:e2e）
5. .mcp.json 含 pwcore/pwvisual
6. .agents/skills/playwright-cli/ 有技能文件
7. AI 记忆三处 Playwright 工具链章节一致
8. 子 app vite.config.ts 端口显式固定
9. artifacts/ 被 gitignore
10. ⚠️ 无头浏览器安全规范已阅读：确认项目属于 3D 大屏类，优先使用 pwvisual（headed）而非 pwcore
11. ⚠️ 浏览器进程回收已检查：tasklist /FI "IMAGENAME eq chrome.exe" 无残留 Chromium 进程