根本原因是Playwright CLI未加入系统PATH；需在项目中本地安装@playwright/test，运行npx playwright install下载浏览器，并在CI中显式安装依赖。
Playwright插件装了但playwright命令报错：command not found
根本原因不是插件没装好，而是playwright CLI 没装到系统 PATH 里。VSCode 插件（如 Playwright Test）只是 UI 层，底层依赖你本地安装的 playwright 包。
实操建议：
- 在项目根目录运行
npm install --save-dev @playwright/test（或yarn add -D @playwright/test），确保node_modules/.bin/playwright存在 - 不要全局安装
npm install -g @playwright/test—— 全局安装后 VSCode 终端可能仍找不到，尤其用 nvm 或 pnpm 时 PATH 更容易混乱 - 打开 VSCode 终端前，先确认当前工作区已加载正确的 Node 版本（看右下角）；如果用了
.nvmrc或.node-version，记得手动nvm use - 验证是否就绪：在 VSCode 集成终端中执行
npx playwright test --version，能输出版本号才算通
点击「录制测试」没反应，或弹出浏览器但不启动录制面板
这是权限和配置组合问题。Playwright 录制功能（playwright codegen）需要明确指定启动方式，VSCode 插件只是调用了它。
实操建议：
- 别直接点插件里的“Record”按钮——它默认尝试读取
playwright.config.ts，若配置缺失或浏览器未声明，会静默失败 - 手动在终端运行：
npx playwright codegen https://example.com，观察控制台是否报错（比如browserType.launch: Executable doesn't exist） - 首次使用必须先下载浏览器：运行
npx playwright install chromium（或firefox/webkit），插件不会自动帮你做这步 - 如果你用的是 Windows + WSL，注意：WSL 中的
codegen无法直接弹出 GUI 浏览器，得切回 Windows 原生终端执行
调试时断点不命中，或 debugger 语句被跳过
Playwright 测试运行在 Node.js 环境，但默认是通过 worker 进程并行执行的，VSCode 的调试器默认连不上这些子进程。
实操建议：
- 必须在
playwright.config.ts中显式启用调试支持：workers: 1（禁用并行）、retries: 0（避免重试干扰）、timeout: 30000（留足调试时间） - 在 VSCode 中按
Ctrl+Shift+P（Win）或Cmd+Shift+P（Mac），输入 “Debug: Select and Start Debugging”，选Playwright Test预设（不是 “Node.js”） - 确保测试文件名匹配默认模式（如
*.spec.ts或*.test.ts），否则调试器找不到入口；可在配置里用testMatch显式指定 -
debugger有效，但console.log输出可能被缓冲——加process.stdout.flush()或用console.error更可靠
测试跑通了，但 CI 里失败，报错 browserType.launch: Executable not found
本地能跑 ≠ CI 能跑。Playwright 浏览器二进制文件默认不进 Git，CI 环境没有自动下载逻辑，靠插件 UI 点点点更不管用。
实操建议：
- CI 脚本里必须显式调用
npx playwright install（或指定浏览器：npx playwright install chromium） - GitHub Actions 示例片段：
run: npx playwright install --with-deps chromium
，--with-deps很关键，它会装系统级依赖（如 libnss3、libgbm1） - GitLab CI 或自建 runner 上，如果用 Docker，优先用官方镜像：
mcr.microsoft.com/playwright:v1.42.0-jammy（对应 Playwright 版本），省去环境适配 - 别在
package.json的postinstall里放playwright install—— 它会在每次npm install时触发，浪费时间且可能权限失败
真正卡住人的地方，往往不是“怎么开始”，而是“谁该负责下载浏览器”——本地开发靠你手动敲命令，CI 靠脚本显式声明，插件 UI 从不替你决定这件事。
