Playwright CDN 连接超时问题解决记录

2026-10-13

问题描述

现象：Playwright 安装浏览器时卡在 0%，最终报错：

Error: connect ETIMEDOUT 28.0.0.32:443
Downloading Chrome for Testing 149.0.7827.55 (playwright chromium v1228) from https://cdn.playwright.dev/builds/cft/149.0.7827.55/win64/chrome-win64.zip

原因：cdn.playwright.dev（CDN 域名）在国内网络环境下被限制或连接不稳定，无法直接建立 HTTPS 连接。

影响范围： - Hermes Desktop 安装器内置的 Playwright 浏览器下载 - 手动执行 npx playwright install chromium（无代理时） - 任何依赖 cdn.playwright.dev 的浏览器安装场景

解决方法

核心方案：通过 HTTP 代理连接 CDN

设置环境变量 HTTPS_PROXY 让 Playwright 走代理通道访问 CDN。

解决步骤

步骤 1：确认代理可用

curl -x http://127.0.0.1:7897 -s -o /dev/null -w "%{http_code}" --max-time 10 https://github.com

返回 200 即表示代理正常工作。

步骤 2：设置环境变量并执行安装

# Linux / macOS / WSL
export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
npx playwright install chromium

# Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
npx playwright install chromium

步骤 3：验证安装结果

ls %LOCALAPPDATA%\ms-playwright\chromium-1228\

确认包含 INSTALLATION_COMPLETE 标记文件和浏览器目录结构（约 416 MB）。

注意事项

1. 环境变量 vs Git 配置的代理

  • npx / npm 等 Node.js 工具只认 HTTPS_PROXY 环境变量，不认 git config http.proxy
  • Git 有自己的代理配置系统，两者是独立的
  • 需要同时配置两者才能让安装全过程都走代理

2. 锁文件问题

  • Playwright 安装时会在 %LOCALAPPDATA%\ms-playwright\__dirlock 创建锁文件
  • 如果之前安装被中断，残留的锁文件会阻止后续所有安装操作
  • 需要清理后再重试：rm -rf %LOCALAPPDATA%\ms-playwright\__dirlock

3. 手动下载替换不生效

  • 直接下载 ZIP 解压到 chromium-1228/ 会被 Playwright 识别为"未使用的浏览器"
  • 安装器会执行 Removing unused browser at ...\chromium-1228 并删除
  • Playwright 需要自身的注册机制（INSTALLATION_COMPLETE 等标记文件）来确认浏览器已安装
  • 必须通过官方 CLI 或 SDK 安装才能被识别

4. 进度显示

  • 通过代理下载时，进度条正常显示（10%、20%...100%）
  • 平均下载时间约 2~5 分钟（取决于代理线路质量）

5. 代理相关注意事项

  • 代理地址和端口（如 127.0.0.1:7897）根据实际使用的代理工具调整
  • 确保代理支持 HTTPS CONNECT 隧道
  • 某些代理可能对 CDN 流量有速度限制

可复用的解决场景

以下类型的网络问题均可复用本方案的 环境变量代理 解决策略：

场景 问题表现 复用方案
npm install 下载包失败 ETIMEDOUT / ERR_CONNECTION_TIMED_OUT 设置 HTTPS_PROXY 环境变量后重试 npm install
pip install 下载 Python 包 Read timed out / Connection broken 设置 HTTPS_PROXY 或配置 pip 的 index-url 镜像源
git clone / git fetch early EOF / RPC failed; curl 92 设置 git config http.proxy 或 HTTPS_PROXY 环境变量
curl / wget 下载文件 连接被重置 / 速度极慢 使用 -x 参数指定代理：curl -x http://proxy:port
一般 GitHub 访问 Connection reset by peer 配置系统全局 HTTP 代理或使用 GitHub 镜像加速
apt/yum 更新 无法连接软件源 配置系统代理或更换国内镜像源

通用解决模式

  1. 识别不可达的域名（如 cdn.playwright.dev、github.com 等）
  2. 检查代理是否可用（curl -x proxy:port https://目标域名）
  3. 将代理注入目标工具的环境变量（HTTPS_PROXY 是最通用的方案）
  4. 如遇锁文件/缓存残留，先清理再重试
  5. 通过 CLI 安装比手动放置文件更可靠（确保有正确的注册信息）

← 返回文章列表