Adam Chow's Life Journals

Appearance

在网络受限环境下为 Playwright 高效安装浏览器依赖 ​

Playwright 在初始化安装时，需要从其官方 CDN 下载 Chromium、Firefox、WebKit 等浏览器内核依赖。然而，在特定网络环境（如企业内网、CI/CD 环境或受网络策略限制的地区），直接访问 cdn.playwright.dev 可能会遇到连接超时或下载速度缓慢的问题，导致安装失败。本文提供一种稳定、高效的解决方案，通过预先下载依赖、本地托管并指定安装源的方式，绕过网络限制，确保 Playwright 环境的顺利搭建。

核心原理 ​

Playwright 提供了灵活的环境变量配置，允许用户覆盖默认的浏览器下载源。我们将利用 PLAYWRIGHT_DOWNLOAD_HOST 这一关键环境变量，将下载请求重定向至一个本地或内部网络中的 HTTP 服务器，从而实现离线安装。

操作步骤 ​

第一步：确定依赖版本与下载地址 ​

Playwright 安装器期望的依赖文件路径和版本是固定的，与你所安装的 playwright 库版本直接相关。为了获取精确的下载列表，请使用 --dry-run 标志，它会列出所有需要下载的 URL 而不执行实际下载。

shell
# 对于 Node.js 项目
npx playwright install --dry-run

# 对于 Python 项目
python -m playwright install --dry-run

执行后，你将看到类似以下的输出，这些就是你需要预先下载的文件的确切 URL：

text
# --- macOS (arm64) 示例 ---
# Playwright 版本：Version 1.55.0
browser: chromium version 140.0.7339.16
  Install location:    /Users/adamzhou/Library/Caches/ms-playwright/chromium-1187
  Download url:        https://cdn.playwright.dev/dbazure/download/playwright/builds/chromium/1187/chromium-mac-arm64.zip
  Download fallback 1: https://playwright.download.prss.microsoft.com/dbazure/download/playwright/builds/chromium/1187/chromium-mac-arm64.zip
  Download fallback 2: https://cdn.playwright.dev/builds/chromium/1187/chromium-mac-arm64.zip

browser: chromium-headless-shell version 140.0.7339.16
  Install location:    /Users/adamzhou/Library/Caches/ms-playwright/chromium_headless_shell-1187
  Download url:        https://cdn.playwright.dev/dbazure/download/playwright/builds/chromium/1187/chromium-headless-shell-mac-arm64.zip
  Download fallback 1: https://playwright.download.prss.microsoft.com/dbazure/download/playwright/builds/chromium/1187/chromium-headless-shell-mac-arm64.zip
  Download fallback 2: https://cdn.playwright.dev/builds/chromium/1187/chromium-headless-shell-mac-arm64.zip

browser: firefox version 141.0
  Install location:    /Users/adamzhou/Library/Caches/ms-playwright/firefox-1490
  Download url:        https://cdn.playwright.dev/dbazure/download/playwright/builds/firefox/1490/firefox-mac-arm64.zip
  Download fallback 1: https://playwright.download.prss.microsoft.com/dbazure/download/playwright/builds/firefox/1490/firefox-mac-arm64.zip
  Download fallback 2: https://cdn.playwright.dev/builds/firefox/1490/firefox-mac-arm64.zip

browser: webkit version 26.0
  Install location:    /Users/adamzhou/Library/Caches/ms-playwright/webkit-2203
  Download url:        https://cdn.playwright.dev/dbazure/download/playwright/builds/webkit/2203/webkit-mac-15-arm64.zip
  Download fallback 1: https://playwright.download.prss.microsoft.com/dbazure/download/playwright/builds/webkit/2203/webkit-mac-15-arm64.zip
  Download fallback 2: https://cdn.playwright.dev/builds/webkit/2203/webkit-mac-15-arm64.zip

browser: ffmpeg
  Install location:    /Users/adamzhou/Library/Caches/ms-playwright/ffmpeg-1011
  Download url:        https://cdn.playwright.dev/dbazure/download/playwright/builds/ffmpeg/1011/ffmpeg-mac-arm64.zip
  Download fallback 1: https://playwright.download.prss.microsoft.com/dbazure/download/playwright/builds/ffmpeg/1011/ffmpeg-mac-arm64.zip
  Download fallback 2: https://cdn.playwright.dev/builds/ffmpeg/1011/ffmpeg-mac-arm64.zip

第二步：创建目录结构并下载依赖文件 ​

根据上一步获取的 URL 路径信息，在本地创建完全一致的目录结构。这是确保 Playwright 安装器能够正确定位到文件的关键。

shell
# --- macOS (arm64) 示例 ---
# 创建一个基础目录用于存放所有依赖
INSTALL_BASE_DIR="/path/to/playwright-deps"
mkdir -p "${INSTALL_BASE_DIR}"
cd "${INSTALL_BASE_DIR}"

# 根据 --dry-run 输出的路径创建子目录
mkdir -p builds/chromium/1187
mkdir -p builds/firefox/1490
mkdir -p builds/webkit/2203
mkdir -p builds/ffmpeg/1011

接下来，使用 wget 或其他下载工具，将文件下载到对应的目录中。请注意，目标文件名也必须与 URL 中的文件名保持一致。

shell
# --- macOS (arm64) 示例 ---
# 注意：请将下面的版本号和文件名替换为你在第一步中获取到的实际值
wget -O builds/chromium/1187/chromium-mac-arm64.zip "https://cdn.playwright.dev/dbazure/download/playwright/builds/chromium/1187/chromium-mac-arm64.zip"
wget -O builds/firefox/1490/firefox-mac-arm64.zip "https://cdn.playwright.dev/dbazure/download/playwright/builds/firefox/1490/firefox-mac-arm64.zip"
wget -O builds/webkit/2203/webkit-mac-15-arm64.zip "https://cdn.playwright.dev/dbazure/download/playwright/builds/webkit/2203/webkit-mac-15-arm64.zip"
wget -O builds/ffmpeg/1011/ffmpeg-mac-arm64.zip "https://cdn.playwright.dev/dbazure/download/playwright/builds/ffmpeg/1011/ffmpeg-mac-arm64.zip"

注意: Windows 或 Linux 用户请下载对应的 *.zip 文件，并确保目录结构正确。

第三步：启动本地 HTTP 服务 ​

在存放依赖的基础目录（即 INSTALL_BASE_DIR）下，启动一个简单的 HTTP 服务器。Python 内置的 http.server 模块是在本地快速启动服务的理想选择。

shell
cd "${INSTALL_BASE_DIR}"
python3 -m http.server 8000
# 服务器将在 http://127.0.0.1:8000 启动

此时，你应该可以通过 http://127.0.0.1:8000/builds/chromium/1187/chromium-mac-arm64.zip 这样的 URL 访问到已下载的文件。

第四步：指定下载源并执行安装 ​

最后，设置 PLAYWRIGHT_DOWNLOAD_HOST 环境变量，指向你刚刚启动的本地服务器地址，然后执行标准的 playwright install 命令。

shell
# 将 PLAYWRIGHT_DOWNLOAD_HOST 指向本地服务器
export PLAYWRIGHT_DOWNLOAD_HOST="http://127.0.0.1:8000"

# 执行安装
# For Node.js
npx playwright install

# For Python
python -m playwright install

Playwright 安装脚本此时会从你的本地服务器请求依赖文件，由于文件已存在于本地，下载过程将瞬间完成，随后自动进行解压和安装。

拓展与最佳实践 ​

  • 企业级方案: 在团队或企业环境中，更推荐将这些浏览器依赖文件托管在内部的制品库（如 Artifactory, Nexus）或对象存储（如 MinIO）上。只需将 PLAYWRIGHT_DOWNLOAD_HOST 指向该内部仓库的地址，即可为所有团队成员和 CI/CD 环境提供一个稳定、高速的依赖源。
  • 管理安装路径: 除了下载源，你还可以通过 PLAYWRIGHT_BROWSERS_PATH 环境变量来指定浏览器依赖的最终安装位置，默认路径通常在用户主目录的缓存文件夹下（如 ~/.cache/ms-playwright）。

总结 ​

通过利用 PLAYWRIGHT_DOWNLOAD_HOST 环境变量，我们可以有效规避因网络问题导致的 Playwright 依赖安装失败，确保开发和部署流程的稳定性和可重复性。该方法不仅适用于个人开发者应对网络限制，也为在隔离网络中配置 CI/CD 流水线提供了可靠的实践方案。