npx playwright install chromium 安装失败，如何离线安装

npx playwright install chromium 安装失败通常是由于网络问题（如连接超时、下载速度慢、被墙等）导致的。Playwright 的 Chromium 浏览器二进制文件较大（通常几百MB），直接在线下载在某些网络环境下不稳定。

以下是 离线安装 Playwright Chromium 的解决方案：

---

✅ 方法一：手动下载 Chromium 并放置到缓存目录（推荐）

这是最可靠、最常用的离线安装方式。

步骤 1：确定 Playwright 的缓存目录

Playwright 默认将浏览器二进制文件缓存到以下路径：

• macOS / Linux:

  ~/.cache/ms-playwright/
  

• Windows:

  %USERPROFILE%\AppData\Local\ms-playwright\
  

你也可以通过命令查看确切路径：

npx playwright install --help

输出中会提示缓存路径，例如：

Path: /Users/yourname/.cache/ms-playwright/chromium-XXXX

步骤 2：获取需要的 Chromium 版本号

运行以下命令查看 Playwright 当前需要安装的 Chromium 版本：

npx playwright install-deps chromium

虽然这行命令可能失败，但它会输出类似：

Installing browsers for playwright@1.25.0
- chromium v1111 (already downloaded)
- firefox v1322
- webkit v1611

你需要的是 chromium v1111 这种格式的版本号（例如 v1111）。

⚠️ 注意：版本号会随 Playwright 版本变化，请以你本地输出为准。

步骤 3：手动下载 Chromium

访问 Playwright 的官方二进制发布地址：

👉 https://github.com/microsoft/playwright/releases

在最新发布的版本页面中，找到类似以下文件：

chromium-linux.zip
chromium-mac.zip
chromium-win64.zip

选择与你系统匹配的包，例如：

• Windows 用户：chromium-win64.zip
• macOS 用户：chromium-mac.zip
• Linux 用户：chromium-linux.zip

💡 提示：如果你无法访问 GitHub，可以使用国内镜像站（如 https://ghproxy.com）加速下载：

例如：

https://ghproxy.com/https://github.com/microsoft/playwright/releases/download/v1.25.0/chromium-win64.zip

步骤 4：解压并放入缓存目录

1. 将下载的 chromium-xxx.zip 解压。

2. 将解压后的文件夹重命名为 chromium-<版本号>，例如 chromium-1111。

3. 将该文件夹复制到 Playwright 的缓存目录：

   # Linux/macOS 示例
   cp -r chromium-1111 ~/.cache/ms-playwright/
   

   :: Windows 示例
   xcopy chromium-1111 "%USERPROFILE%\AppData\Local\ms-playwright\chromium-1111" /E
   

步骤 5：验证安装

运行：

npx playwright install chromium

如果已检测到浏览器，会显示：

Chromium (v1111) already downloaded

表示安装成功！

---

✅ 方法二：使用环境变量指定镜像源（适合网络受限但可部分访问）

你可以通过设置环境变量，让 Playwright 使用国内镜像下载。

# 使用淘宝镜像
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium

或设置为全局环境变量：

# Linux/macOS
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
npx playwright install chromium# Windows (PowerShell)
$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"
npx playwright install chromium

📌 镜像地址：

• 淘宝镜像：https://npmmirror.com/mirrors/playwright
• 腾讯云镜像：https://mirrors.cloud.tencent.com/npm/playwright-api/

---

✅ 方法三：使用 --offline 模式（配合预下载）

如果你在无网络环境，可以提前在有网络的机器上安装好，然后拷贝整个缓存目录。

# 在有网络的机器上执行
npx playwright install chromium# 打包缓存目录
tar -czf playwright-browsers.tar.gz ~/.cache/ms-playwright/

然后将 playwright-browsers.tar.gz 拷贝到目标机器，解压到对应路径即可。

---

🔍 验证是否成功

运行一个简单脚本测试：

// test.js
const { chromium } = require('playwright');(async () => {const browser = await chromium.launch();const page = await browser.newPage();await page.goto('https://example.com');await page.screenshot({ path: 'example.png' });await browser.close();
})();

运行：

node test.js

如果能正常截图，说明 Chromium 安装成功。

---

总结

方法	适用场景
手动下载 + 放入缓存	网络差、完全无法下载
使用镜像源环境变量	网络慢但可访问镜像
拷贝缓存目录	批量部署、离线环境

推荐优先尝试 方法一（手动下载），最稳定可控。

如有具体错误信息（如 ERR_CONNECTION_TIMEOUT），可提供日志进一步分析。