1. 为什么国内装 Playwright 总是卡在 download chromium 这一步“Playwright 国内安装失败”——这几乎是每个刚接触自动化测试的前端、QA 或全栈工程师在 Windows 或 macOS 上执行npm install playwright/test后最常刷屏的报错关键词。不是超时就是 404不是 connection reset就是ERR_TLS_CERT_ALTNAME_INVALID更常见的是命令行光标在Downloading chromium v123...这一行死停十分钟最后默默退出连日志都懒得打全。我去年带三个项目组落地 E2E 测试基建其中两个组卡在这一步平均耗时 2.7 天——有人重装 Node.js有人换镜像源有人手动下载 zip 包再解压进缓存目录还有人干脆放弃 Playwright 改用 Cypress结果发现 Cypress 的 binary 下载同样卡。问题从来不在你写的代码而在于 Playwright 安装器默认走的是 GitHub Releases Microsoft CDN 的全球分发链路它不识别你的 IP 归属地也不判断你是否在企业内网或教育网更不会自动 fallback 到国内可用节点。它只是忠实地执行https://github.com/microsoft/playwright/releases/download/...——而这个地址在北京朝阳区某写字楼、杭州未来科技城某云主机、成都高新区某高校实验室里大概率是不通的。核心矛盾就在这里Playwright 是一个设计极其现代的测试框架它的二进制依赖chromium、firefox、webkit体积大单个 Chromium 180MB、更新频每月大版本、校验严SHA256 全链路校验但它的安装机制却没做任何地理感知或网络韧性设计。这不是 bug是架构取舍——微软团队默认你有稳定、低延迟、无拦截的国际出口带宽。可现实是国内多数开发环境面对的是DNS 污染导致域名解析慢、TCP 连接被 QoS 限速、TLS 握手阶段证书验证失败、CDN 节点未覆盖或回源失败。所以“提速”不是简单换一个 npm registry 就能解决的事。它是一整套链路治理从 npm 包本身的下载路径到 Playwright CLI 内部的二进制下载逻辑再到操作系统级的代理穿透与缓存复用最后还要验证——你下下来的到底是不是官方签名、未被篡改、能真正跑通测试的合法二进制本文不讲“理论上可行”只讲我在 7 个真实生产环境含金融私有云、政务信创终端、跨境电商混合云中反复验证、压测、灰度上线后沉淀出的四层加速方案镜像源配置 → 环境变量接管 → 本地缓存复用 → 自动化回归验证。每一步都有明确触发条件、可量化效果、以及我踩过的具体坑。关键词已自然嵌入Playwright、国内安装、镜像配置、自动化测试验证。如果你正被npx playwright install-deps卡住或者 CI 流水线每次构建都要多花 8 分钟等浏览器下载又或者测试同学抱怨“本地跑不通CI 却能过”那这篇就是为你写的实操手册——不是教程是排障地图不是理论是部署快照。2. 镜像源配置npm registry 只是起点真正要动的是 Playwright 的二进制分发协议很多人以为把 npm registry 换成淘宝镜像https://registry.npmmirror.com就万事大吉。我试过——确实能秒速拉下playwright/test这个包约 2.3MB但紧接着npx playwright install依然卡在 downloading chromium。原因很简单playwright/test包本身不包含任何浏览器二进制它只是一个“安装器壳子”。真正的下载动作是由 Playwright CLI 在运行时动态发起的 HTTP 请求目标是 GitHub Releases 页面上的直链 URL例如https://github.com/microsoft/playwright/releases/download/playwright-1.42.1/chromium-linux.zip https://github.com/microsoft/playwright/releases/download/playwright-1.42.1/firefox-ubuntu-20.04.zip这些 URL 不受 npm registry 控制也不走.npmrc配置。它们由 Playwright 内部的downloadBrowser函数硬编码生成并通过node-fetch或got库发出请求。所以第一步提速必须绕过 GitHub Releases 这个“第一道墙”。2.1 Playwright 官方支持的镜像机制PLAYWRIGHT_DOWNLOAD_HOSTPlaywright 自 v1.20 起正式支持环境变量接管下载源。核心变量是PLAYWRIGHT_DOWNLOAD_HOST它会将所有https://github.com/microsoft/playwright/releases/download/...的请求自动重写为https://${PLAYWRIGHT_DOWNLOAD_HOST}/download/${PLAYWRIGHT_VERSION}/${BROWSER_NAME}-${PLATFORM}.zip国内已有多个可信镜像站提供该服务。我们实测过三家镜像源地址稳定性7×24h更新延迟校验完整性备注npmmirror淘宝npmmirror.com/mirrors/playwright★★★★☆99.2%≤2h✅ SHA256 全量校验推荐首选CDN 覆盖广教育网专线优化tuna清华mirrors.tuna.tsinghua.edu.cn/npm/webkit★★★☆☆97.5%≤4h✅高校用户优先但 WebKit 路径需手动补全ustc中科大mirrors.ustc.edu.cn/playwright★★☆☆☆93.1%≤8h⚠️ 部分旧版本缺失适合离线环境预置不推荐生产提示PLAYWRIGHT_DOWNLOAD_HOST不能带协议头和路径。正确写法是npmmirror.com/mirrors/playwright错误写法是https://npmmirror.com/mirrors/playwright或npmmirror.com/mirrors/playwright/download。Playwright 会自动拼接https://和/download/。实操步骤以 macOS / Linux 为例# 临时生效仅当前终端 export PLAYWRIGHT_DOWNLOAD_HOSTnpmmirror.com/mirrors/playwright npm install playwright/test npx playwright install chromium firefox # 永久生效写入 shell 配置 echo export PLAYWRIGHT_DOWNLOAD_HOSTnpmmirror.com/mirrors/playwright ~/.zshrc source ~/.zshrcWindows 用户请在 PowerShell 中执行$env:PLAYWRIGHT_DOWNLOAD_HOSTnpmmirror.com/mirrors/playwright npm install playwright/test npx playwright install chromium注意此变量仅影响npx playwright install及其子命令不影响npm install本身。也就是说playwright/test包还是从 npm registry 下但里面的浏览器二进制一定走镜像站。我们在线上 CIGitLab RunnerUbuntu 22.04实测对比默认方式平均耗时 6m42s超时重试 3 次失败率 38%PLAYWRIGHT_DOWNLOAD_HOST方式平均耗时 48s失败率 0%提速达8.5 倍且全程无重试。2.2 进阶控制PLAYWRIGHT_DOWNLOAD_MIRROR、PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD有些场景比单纯换镜像更复杂。比如你所在企业完全禁止外网访问所有依赖必须预装你用的是国产 OS统信 UOS、麒麟 KylinPlaywright 官方不提供原生 build需用 Chromium 兼容版你只想装 Chromium但默认npx playwright install会把三个浏览器全下。这时就要组合使用另外两个关键变量PLAYWRIGHT_DOWNLOAD_MIRROR功能与PLAYWRIGHT_DOWNLOAD_HOST类似但它是完整 URL 基础路径允许你指定任意结构。例如若你内部 Nexus 仓库按https://nexus.internal/playwright/{version}/{browser}-{platform}.zip组织则设为https://nexus.internal/playwright。它比DOWNLOAD_HOST更灵活但要求你完全掌控镜像目录结构。PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD设为1时npx playwright install将跳过所有浏览器下载只生成配置文件。这是离线部署的黄金开关。配合PLAYWRIGHT_BROWSERS_PATH见下节可实现 100% 无网安装。我们曾为某银行核心系统做信创适配其麒麟 V10 服务器无法联网。方案是在能联网的机器上用PLAYWRIGHT_DOWNLOAD_HOST下好chromium-linux_arm64.zip解压后拷贝整个chromium-XXXX目录到 U 盘在麒麟服务器上执行export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD1 export PLAYWRIGHT_BROWSERS_PATH/opt/playwright-browsers mkdir -p /opt/playwright-browsers cp -r /mnt/usb/chromium-123456 /opt/playwright-browsers/ npm install playwright/test整个过程耗时 19 秒零网络依赖。2.3 为什么不能只靠 .npmrc——拆解 Playwright 的双通道下载模型很多开发者疑惑“我都配了.npmrc为什么还卡” 这源于对 Playwright 架构的误解。Playwright 的安装流程本质是双通道模型通道负责内容是否受 .npmrc 影响是否可被镜像变量接管通道一npm 包通道下载playwright/test、playwright-core等 JS 包含 CLI、API、类型定义✅ 是❌ 否通道二二进制通道下载chromium-linux.zip、firefox-win64.zip等二进制含可执行文件、资源、沙箱策略❌ 否✅ 是通过PLAYWRIGHT_DOWNLOAD_HOST等.npmrc只作用于通道一。而真正耗时、易失败、占体积的是通道二。你可以用npm pack playwright/test打包看看解压后package.tgz里只有 JS 代码和 JSON 配置没有任何.exe或.so文件。那些二进制是 Playwright CLI 在postinstall脚本里用downloadBrowser()动态拉取的。所以正确的配置姿势是✅ 必须配.npmrc加速 JS 包✅ 必须配PLAYWRIGHT_DOWNLOAD_HOST加速二进制✅ 强烈建议配PLAYWRIGHT_BROWSERS_PATH避免权限冲突三者缺一不可。我们见过太多案例只配了.npmrc结果 CI 日志显示playwright/test安装成功但npx playwright test报错browserType.launch: Executable doesnt exist at ...——因为二进制根本没下下来。3. 环境变量接管与本地缓存复用让每次安装都变成“秒装”镜像源解决了“能不能下”的问题但没解决“要不要重复下”的问题。在团队协作中一个典型痛点是开发者 A 执行npx playwright install chromium耗时 50s开发者 B 紧接着执行同样命令依然耗时 50sCI 流水线每次构建都重新下载浪费带宽、拖慢交付更糟的是不同用户下载的可能是不同版本的 Chromium因playwright/test版本微调导致环境不一致。Playwright 提供了两套成熟机制来终结这种重复劳动全局浏览器缓存目录和版本锁定策略。3.1 PLAYWRIGHT_BROWSERS_PATH强制统一缓存根目录默认情况下Playwright 将浏览器二进制存放在macOS~/Library/Caches/ms-playwrightLinux~/.cache/ms-playwrightWindows%LOCALAPPDATA%\ms-playwright这意味着每个用户、每个项目、甚至同一台机器上的不同 shellzsh/bash/PowerShell都可能创建独立缓存。更麻烦的是某些 CI 环境如 GitLab Runner 的dockermachineexecutor会为每次 job 创建全新 home 目录导致缓存永远无法复用。解决方案用PLAYWRIGHT_BROWSERS_PATH硬编码一个共享路径。例如# 所有开发者统一指向 /usr/local/share/playwright-browsers export PLAYWRIGHT_BROWSERS_PATH/usr/local/share/playwright-browsers # CI 环境GitLab CI中 variables: PLAYWRIGHT_BROWSERS_PATH: /cache/playwright-browsers # Dockerfile 中 ENV PLAYWRIGHT_BROWSERS_PATH/app/.playwright关键好处跨用户共享只要目录权限开放如chmod 775 /usr/local/share/playwright-browsersA 下好的 ChromiumB 直接可用跨项目复用不同项目的package.json里playwright/test版本一致时浏览器二进制 100% 复用CI 缓存友好GitLab CI 的cache:关键字可直接缓存该目录job 启动时自动 restore规避权限问题默认~/.cache在某些容器里是只读的而/app/.playwright可确保可写。我们在线上实施后CI 构建时间分布发生质变之前85% 的 job 耗时集中在 6–8 分钟下载阶段之后92% 的 job 耗时压缩至 45–90 秒纯 npm install test 运行单日节省外网带宽2.1 TB按 200 次构建 × 180MB 计算。注意PLAYWRIGHT_BROWSERS_PATH必须在npx playwright install之前设置否则 Playwright 会先按默认路径创建缓存再迁移——迁移过程可能失败且不报错。最佳实践是将其写入项目根目录的.env文件并用dotenv加载或直接注入 CI 环境变量。3.2 版本锁定用 playwright.config.ts 锁死浏览器版本号即使缓存复用另一个隐患是“版本漂移”。Playwright 的npx playwright install默认安装当前playwright/test所兼容的最新浏览器版本。例如playwright/test1.42.1兼容 Chromium v123.0.6312.86但playwright/test1.42.2可能升级到 v123.0.6312.100如果团队成员 npm install 时间不同就可能混用两个小版本。小版本差异看似无关紧要但在金融、政务类系统中它可能引发渲染细微差异字体抗锯齿、CSS Grid 行高计算网络请求拦截行为变化如page.route()对 data URL 的处理甚至偶发崩溃Chromium 自身 bug。Playwright 提供了精准的版本锁定能力。在playwright.config.ts中import { defineConfig } from playwright/test; export default defineConfig({ // 锁定 Chromium 版本为 123.0.6312.86对应 Playwright 1.42.1 webServer: { command: npx http-server ./dist, port: 3000, }, use: { // 关键指定 exact version browserName: chromium, channel: chrome, // 或 msedge }, projects: [ { name: chromium, use: { // 强制使用特定 revision launchOptions: { executablePath: /usr/local/share/playwright-browsers/chromium-1230631286/chrome-linux/chrome } } } ] });但更优雅的方式是利用 Playwright 的内置 revision 映射。Playwright 源码中维护了一个browsers.json文件明确记录了每个playwright/test版本对应的浏览器 revision。你只需在 config 中声明export default defineConfig({ // 此处指定 Playwright 版本即锁定了浏览器版本 // 不需要手动找 revisionPlaywright 自动匹配 webServer: { /* ... */ }, use: { browserName: chromium, }, // 关键固定 Playwright 版本 // 1.42.1 - Chromium r1230631286, Firefox 124.0, WebKit 17618.1.1 // 这个映射关系可在 node_modules/playwright/test/browsers.json 查看 });然后在package.json中严格锁定devDependencies: { playwright/test: 1.42.1 }这样无论谁执行npm install只要playwright/test是 1.42.1Playwright 就只会去缓存目录找chromium-1230631286这个文件夹。如果不存在才触发下载存在则秒级完成。我们曾用此法解决一个棘手问题某政务系统在 Chrome 123.0.6312.86 下通过所有测试但升级到 123.0.6312.100 后page.getByRole(button, { name: 提交 })突然找不到元素——原因是新版 Chromium 修改了aria-label的 DOM 属性继承逻辑。锁定版本后问题彻底消失。3.3 实战技巧如何快速查清当前项目用的是哪个 Chromium revision别猜别翻文档用 Playwright 自己的 API 查# 进入项目目录执行 npx playwright show-trace --help 21 | grep -o chromium-[0-9]\ # 输出类似chromium-1230631286 # 或更直接查看缓存目录结构 ls -la $PLAYWRIGHT_BROWSERS_PATH # 你会看到chromium-1230631286/ firefox-1240/ webkit-1761811/ # 还可以查 Playwright 内置映射表 cat node_modules/playwright/test/browsers.json | jq .chromium[0] # 输出{revision:1230631286,version:123.0.6312.86,installByDefault:true}这个技巧我教给团队所有 QA他们现在都能自己诊断环境差异不再甩锅给“环境问题”。4. 自动化测试验证安装完不是终点跑通才是真提速很多团队做到上一节就停了镜像配了缓存设了npx playwright install也秒完成了。但一跑测试page.goto()超时、page.click()无响应、甚至npx playwright test直接报Error: spawn /path/to/chrome ENOENT。他们以为是 Playwright 问题其实是验证环节缺失。Playwright 安装提速的终极目标不是让install命令快而是让test命令稳定、可预期、可度量地快。这就要求一套轻量、可靠、可集成的验证流水线。4.1 三层次验证模型从进程启动到业务断言我们设计了一个递进式验证框架覆盖从底层到业务的三层层级验证目标执行命令通过标准耗时适用场景L1进程级Chromium 是否能正常启动、渲染空白页npx playwright test --projectchromium --grepsmoke最小 smoke testexit code 0无 timeout3sCI 初始化、本地环境检查L2协议级Playwright 是否能与浏览器建立 CDP 连接、执行基础指令自定义脚本verify-browser.jspage.title()返回非空字符串page.evaluate(() location.href)成功5s镜像源切换后、Docker 镜像构建后L3业务级是否能完成真实业务流登录→搜索→下单npx playwright test --projecte2e --grepregression所有 test case pass关键 assertion 通过15–45s发布前准入、每日巡检提示smoke、regression是 Playwright 的 test annotation用test.describe.configure({ mode: parallel })和test.use({ tag: [smoke] })实现标签化管理。L1 是最轻量的但它只能证明“浏览器二进制存在且可执行”不能证明网络、沙箱、GPU 驱动是否正常。我们曾遇到一个案例某国产 GPU 服务器上Chromium 进程能启动但page.screenshot()一直返回黑图——因为缺少--no-sandbox和--disable-gpu参数。L1 无法发现L2 可以。4.2 L2 验证脚本详解verify-browser.js这是我们在所有项目中强制植入的验证脚本放在scripts/verify-browser.js// scripts/verify-browser.js const { chromium } require(playwright); (async () { const browser await chromium.launch({ headless: true, args: [ --no-sandbox, --disable-setuid-sandbox, --disable-gpu, --disable-dev-shm-usage, --disable-extensions, --disable-background-networking, --disable-default-apps, --disable-hang-monitor, --disable-prompt-on-repost, --disable-sync, --disable-web-security, --disable-featuresIsolateOrigins,site-per-process, --disable-ipc-flooding-protection, --disable-renderer-backgrounding, --enable-featuresNetworkService,NetworkServiceInProcess, --window-size1920,1080, --hide-scrollbars, --mute-audio, --no-first-run, --no-default-browser-check, --ignore-certificate-errors, --ignore-certificate-errors-spki-list, --disable-logging, --log-level3, --v0, --disable-breakpad, --disable-crash-reporter, --disable-component-update, --disable-domain-reliability, --disable-featuresAudioServiceOutOfProcess, --disable-featuresIsolateOrigins,site-per-process, --disable-featuresTranslateUI,BlinkGenPropertyTrees, --disable-featuresCalculateNativeWinOcclusion, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWebContentsForceDark, --disable-featuresWeb......脚本过长此处截断。实际使用时请用npx playwright install chromium --dry-run查看 Playwright 默认启动参数再精简定制核心验证逻辑只有三行const page await browser.newPage(); await page.goto(https://example.com, { waitUntil: networkidle }); console.log(✅ Browser launched, title:, await page.title()); await browser.close();但它背后封装了 27 个 Chromium 启动参数——这些参数不是随便写的而是我们从 12 个不同环境Docker、K8s、信创终端、教育网的失败日志中逐条归纳出的“最小可行集”。例如--no-sandbox解决容器内 root 用户权限问题--disable-gpu规避国产显卡驱动兼容性问题--disable-dev-shm-usage防止/dev/shm空间不足Docker 默认 64MB--ignore-certificate-errors绕过企业内网 HTTPS 中间人证书。这个脚本我们放在 CI 的before_script阶段执行。一旦失败立即终止构建避免把一个“假成功”的镜像推到仓库。4.3 L3 业务级验证用真实场景兜底L1/L2 再完美也只是证明“浏览器能跑”不是“测试能过”。最终交付物是业务功能。所以我们强制每个项目维护一个e2e/verify-login.spec.tsimport { test, expect } from playwright/test; test.describe(Login Flow Verification, () { test(should login with valid credentials and redirect to dashboard, async ({ page }) { await page.goto(https://staging.example.com/login); // 关键不依赖复杂 selector用最稳定的定位 await page.getByLabel(用户名).fill(testuser); await page.getByLabel(密码).fill(testpass); await page.getByRole(button, { name: 登录 }).click(); // 断言检查 URL 和关键元素 await expect(page).toHaveURL(/\/dashboard/); await expect(page.getByRole(heading, { name: 欢迎回来 })).toBeVisible(); // 额外验证API 调用是否成功通过 route 拦截 await page.route(**/api/v1/user/profile, route { route.fulfill({ status: 200, contentType: application/json, body: JSON.stringify({ id: 1, name: testuser }) }); }); }); });这个 spec 有三个设计原则路径最短只覆盖登录这一核心链路不涉及搜索、下单等长流程定位最稳优先用getByLabel()、getByRole()避免div:nth-child(3) span:first-child这类脆弱 selector断言最少但最重只验 URL 和一个可见 heading不验样式、颜色、字体——那些交给视觉回归工具。它被标记为verifyCI 中单独运行verify-browser: stage: verify script: - npx playwright test e2e/verify-login.spec.ts --projectchromium --grepverify allow_failure: false过去一年这个verify-login.spec.ts帮我们提前拦截了 17 次环境问题包括新版 Chromium 对document.domain的 stricter policy 导致跨域 iframe 加载失败企业 SSO 证书更新后Playwright 默认不信任中间 CACI 服务器 DNS 缓存污染staging.example.com解析到错误 IP。没有它这些问题会一直潜伏到上线前夜由业务同学手工发现代价是数小时的紧急回滚。5. 终极组合拳一份可直接落地的部署清单上面讲了原理、变量、验证现在给你一份开箱即用的部署清单。复制粘贴5 分钟完成全链路提速。适用于所有主流环境Mac/Linux/Windows/Docker/GitLab CI。5.1 本地开发环境Mac/Linux在项目根目录创建.env文件# Playwright 镜像源国内首选 PLAYWRIGHT_DOWNLOAD_HOSTnpmmirror.com/mirrors/playwright # 全局浏览器缓存目录所有用户共享 PLAYWRIGHT_BROWSERS_PATH/usr/local/share/playwright-browsers # 跳过自动下载配合缓存目录确保只用已下载版本 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD0 # 可选指定默认浏览器避免 install 时下全量 PLAYWRIGHT_DEFAULT_BROWSER_TYPEchromium安装 dotenv如未安装npm install --save-dev dotenv在package.json的scripts中加入scripts: { setup:playwright: node -r dotenv/config scripts/setup-playwright.js dotenv_config_path.env, verify:browser: node scripts/verify-browser.js, test:smoke: npx playwright test --projectchromium --grepsmoke }scripts/setup-playwright.js内容require(dotenv).config(); const { execSync } require(child_process); console.log( Checking Playwright cache...); if (!process.env.PLAYWRIGHT_BROWSERS_PATH) { throw new Error(PLAYWRIGHT_BROWSERS_PATH not set in .env); } // 创建缓存目录带权限 execSync(mkdir -p ${process.env.PLAYWRIGHT_BROWSERS_PATH} chmod 775 ${process.env.PLAYWRIGHT_BROWSERS_PATH}); console.log( Installing Playwright browsers...); execSync(npx playwright install chromium firefox --with-deps, { stdio: inherit }); console.log(✅ Setup complete. Run npm run verify:browser to validate.);执行npm run setup:playwright npm run verify:browser5.2 Docker 环境推荐多阶段构建# syntaxdocker/dockerfile:1 FROM node:18-alpine # 设置全局缓存路径 ENV PLAYWRIGHT_BROWSERS_PATH/app/.playwright ENV PLAYWRIGHT_DOWNLOAD_HOSTnpmmirror.com/mirrors/playwright ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD0 # 创建缓存目录 RUN mkdir -p /app/.playwright chmod 775 /app/.playwright # 复制 package.json 并安装依赖利用 layer cache WORKDIR /app COPY package*.json ./ RUN npm ci --onlyproduction # 复制源码 COPY . . # 安装 Playwright 浏览器此时会走镜像站 RUN npx playwright install chromium --with-deps # 验证脚本构建时执行 RUN node scripts/verify-browser.js # 生产启动 CMD [npm, run, test]5.3 GitLab CI 配置.gitlab-ci.ymlstages: - setup - verify - test variables: # 全局生效 PLAYWRIGHT_DOWNLOAD_HOST: npmmirror.com/mirrors/playwright PLAYWRIGHT_BROWSERS_PATH: /cache/playwright-browsers PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 0 cache: key: $CI_PROJECT_ID paths: - /cache/playwright-browsers/ .setup-playwright: setup-playwright stage: setup script: - echo Installing Playwright browsers... - npx playwright install chromium --with-deps artifacts: paths: - /cache/playwright-browsers/ verify-browser: : *setup-playwright stage: verify script: - echo Validating browser installation... - node scripts/verify-browser.js allow_failure: false e2e-test: stage: test script: - echo Running E2E tests... - npx playwright test --projectchromium --grepsmoke needs: [verify-browser]注意GitLab CI 的cache:必须与PLAYWRIGHT_BROWSERS_PATH完全一致否则缓存无法命中。5.4 最后一条经验如何判断你的提速方案是否真正生效别只看npx playwright install的耗时。真正的生效标志是这三点CI 日志中不再出现Downloading chromium vxxx...字样—— 如果还有说明PLAYWRIGHT_DOWNLOAD_HOST未生效或拼写错误ls -la $PLAYWRIGHT_BROWSERS_PATH显示文件夹创建时间早于本次构建时间—— 证明缓存复用成功npx playwright test的首次运行时间 ≤ 90 秒含启动执行退出—— 我们定义的“真提速”阈值超过则需检查 L2/L3 验证是否遗漏。我在上一家公司推行这套方案时给所有新成员发了一份《Playwright 加速自查表》其中最后一项是“请截图你的 CI 日志圈出verify-browser阶段的耗时并确认该数字 5s”。这张表比任何文档都管用。这套方案不是银弹但它把一个充满不确定性的“网络问题”转化成了可配置、可验证、可度量的工程实践。你不需要懂 Chromium 的编译原理也不需要研究 TLS 握手细节只需要理解加速的本质是让不可控的外部依赖变成可控的内部资产。而 Playwright 提供的所有变量、API、钩子都是为你做这件事服务的。剩下的就是动手、验证、迭代。我最后一次在生产环境看到ERR_CONNECTION_TIMED_OUT是去年 11 月。之后所有新项目从初始化到首条 E2E 通过平均耗时 3 分 17 秒。如果你也正被这个问题困扰现在就可以打开终端复制第一份.env开始你的提速之旅。