Playwright 浏览器安装慢？一文搞定国内加速方案

npx playwright install chromium 下载龟速甚至超时？本文给出手动下载离线安装方案，彻底解决国内网络下 Playwright 浏览器安装慢的问题。

问题：下载慢到怀疑人生

执行 npx playwright install chromium 时，Playwright 会从 cdn.playwright.dev 下载对应平台的 Chrome for Testing 二进制包。这个 CDN 在国内访问速度极不稳定，经常出现：

$ npx playwright install chromium
Downloading Chrome for Testing 147.0.7727.15 (playwright chromium v1217)
from https://cdn.playwright.dev/builds/cft/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip
165.5 MiB [=                   ] 3% 674.5s
# 下载速度慢到 100KB/s，甚至直接超时失败

背景：为什么镜像源不好使了

先说结论：如果你用的是 Playwright v1.58+，网上大部分镜像加速教程已经失效了。

发生了什么

Playwright v1.58.0（2026 年 1 月发布）将 Chromium 下载切换为 Chrome for Testing (cft)，URL 路径从：

# 旧版（v1.57 及之前）
https://cdn.playwright.dev/builds/chromium/1208/chromium-mac-arm64.zip

# 新版（v1.58+）
https://cdn.playwright.dev/builds/cft/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip

关键问题在于，builds/cft/ 这个路径前缀是硬编码在 Playwright 源码中的：

// playwright-core/src/server/registry/index.ts
function cftUrl(suffix: string): DownloadPathFunction {
  return ({ browserVersion }) => {
    return {
      path: `builds/cft/${browserVersion}/${suffix}`,  // 硬编码，无法覆盖
      mirrors: ['https://cdn.playwright.dev'],
    };
  };
}

当你设置 PLAYWRIGHT_DOWNLOAD_HOST 时，它只替换 cdn.playwright.dev 这个域名部分，builds/cft/ 会原封不动地拼接上去。

npmmirror 镜像为什么 404

npmmirror 的 chrome-for-testing 镜像文件实际存放在：

https://cdn.npmmirror.com/binaries/chrome-for-testing/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip

但 Playwright 拼接出来的请求是：

https://cdn.npmmirror.com/binaries/playwright/builds/cft/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip
                                                  ^^^^^^^^^^
                                                  多了 builds/cft/ 前缀，404！

路径不匹配，所以 404。 这个问题在 Playwright 和 npmmirror 两边都已知（Playwright Issue #39430），但截至 2026 年 4 月仍未解决——双方互推责任。

影响范围

浏览器	是否受影响	说明
Chromium	受影响	v1.58+ 使用 cft 路径，镜像 404
Firefox	不受影响	仍用旧路径，镜像正常
WebKit	不受影响	仍用旧路径，镜像正常

了解了背景，下面给出实际可用的解决方案。

解决方案：手动下载 + 离线安装

虽然 PLAYWRIGHT_DOWNLOAD_HOST 走不通，但 npmmirror 上确实有 Chrome for Testing 的文件，只是路径结构不同，需要手动下载后放到正确位置。

第 1 步：确认需要的版本

npx playwright install chromium --dry-run

输出中会包含版本号和构建号，比如：

Chrome for Testing 147.0.7727.15 (playwright chromium v1217)
  Install location:    ~/Library/Caches/ms-playwright/chromium-1217
  Download url:        https://cdn.playwright.dev/builds/cft/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip

记住版本号 147.0.7727.15 和构建号 1217。

第 2 步：从 npmmirror 下载

npmmirror 的 chrome-for-testing 镜像地址格式（注意：没有 builds/cft/ 前缀）：

https://cdn.npmmirror.com/binaries/chrome-for-testing/<version>/<platform>/chrome-<platform>.zip

各平台对应：

系统	platform 值
macOS (Intel)	`mac-x64`
macOS (Apple Silicon)	`mac-arm64`
Linux x64	`linux64`
Windows x64	`win64`

比如 Apple Silicon macOS：

# 下载 Chrome for Testing
curl -O https://cdn.npmmirror.com/binaries/chrome-for-testing/147.0.7727.15/mac-arm64/chrome-mac-arm64.zip

# 下载 Headless Shell（部分测试场景需要）
curl -O https://cdn.npmmirror.com/binaries/chrome-for-testing/147.0.7727.15/mac-arm64/chrome-headless-shell-mac-arm64.zip

第 3 步：解压到 Playwright 缓存目录

# Playwright 默认缓存路径：
# macOS:   ~/Library/Caches/ms-playwright
# Linux:   ~/.cache/ms-playwright
# Windows: %LOCALAPPDATA%\ms-playwright

# 解压 Chrome for Testing（构建号 v1217 对应目录名 chromium-1217）
unzip chrome-mac-arm64.zip -d ~/Library/Caches/ms-playwright/chromium-1217/

# 解压 Headless Shell
unzip chrome-headless-shell-mac-arm64.zip -d ~/Library/Caches/ms-playwright/chromium_headless_shell-1217/

第 4 步：创建标记文件（关键！）

Playwright 靠两个标记文件来判断浏览器是否"合法安装"。如果缺少这两个文件，下次执行 npx playwright install 时会把手动解压的目录当成 "unused" 直接删掉，然后重新从 CDN 下载。

# Chrome for Testing 标记文件
touch ~/Library/Caches/ms-playwright/chromium-1217/INSTALLATION_COMPLETE
touch ~/Library/Caches/ms-playwright/chromium-1217/DEPENDENCIES_VALIDATED

# Headless Shell 标记文件
touch ~/Library/Caches/ms-playwright/chromium_headless_shell-1217/INSTALLATION_COMPLETE
touch ~/Library/Caches/ms-playwright/chromium_headless_shell-1217/DEPENDENCIES_VALIDATED

最终目录结构应该是：

chromium-1217/
├── INSTALLATION_COMPLETE        # 空文件，标记安装完成
├── DEPENDENCIES_VALIDATED       # 空文件，标记依赖验证通过
└── chrome-mac-arm64/
    ├── Google Chrome for Testing.app/
    └── ...

第 5 步：验证

$ npx playwright install --list

Playwright version: 1.59.1
  Browsers:
    ~/Library/Caches/ms-playwright/chromium-1217
    ~/Library/Caches/ms-playwright/chromium_headless_shell-1217
    ~/Library/Caches/ms-playwright/ffmpeg-1011

chromium-1217 和 chromium_headless_shell-1217 都出现，说明安装成功。再次执行 npx playwright install chromium 也不会重新下载。

常见问题

Q：这个镜像问题什么时候能修？

截至 2026 年 4 月，Playwright 方面（Issue #39430）和 npmmirror 方面互推责任：

Playwright 认为是镜像方该适配新路径
npmmirror 认为是 Playwright 该让路径前缀可配置

短期内不太可能有官方修复，建议用手动下载方案。

Q：Firefox 和 WebKit 也需要特殊处理吗？

不需要。Firefox 和 WebKit 不受 cft 路径问题影响，可以直接用镜像：

export PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright
npx playwright install firefox webkit
# 正常下载，不会 404

只有 Chromium 需要手动下载。

Q：PLAYWRIGHT_DOWNLOAD_HOST 和 PLAYWRIGHT_BROWSERS_PATH 有什么区别？

PLAYWRIGHT_DOWNLOAD_HOST：控制从哪里下载
PLAYWRIGHT_BROWSERS_PATH：控制安装到哪个目录

两者可以组合使用。

Playwright 浏览器安装慢？一文搞定国内加速方案

On this page