Playwright 浏览器可执行文件缺失 — 安装失败

症状

本篇指南处理“Playwright 浏览器可执行文件缺失 — 安装失败”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。

可观察到的症状包括：

• Playwright 报 “Executable doesn’t exist at … chromium-…”
• 测试在开发机通过，在 CI 失败
• 错误提示应运行 playwright install

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

npx playwright install --with-deps chromium

这会下载二进制及其系统依赖，解决可执行文件缺失。

步骤 2

npx playwright install --dry-run

dry run 会打印预期的二进制位置与版本，便于与错误对照。

常见诱因（按出现频率排序）：

• 浏览器二进制未下载（全新安装或缓存未命中）
• 浏览器版本升级使缓存的二进制失效
• 精简容器中缺少浏览器所需的系统库

根因

Playwright 的浏览器二进制与其 npm 包分开下载，并按版本区分。全新环境或版本升级却没有对应下载时，便无可执行文件，运行器无法启动浏览器。

修复

在安装步骤运行 npx playwright install –with-deps，让浏览器缓存键与 Playwright 版本对齐，并在使用精简基础镜像时安装系统库。

注意：用陈旧键缓存浏览器会复用不同版本的二进制并引发隐蔽的启动失败；缓存键应基于版本。

# install browsers and OS deps
npx playwright install --with-deps

# GitHub Actions: cache keyed on the Playwright version
- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

- run: npx playwright install --with-deps chromium

验证

运行测试套件并确认浏览器启动且测试执行；验证安装步骤报告预期版本。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。