🚀 Playwright 手动安装 Chromium 完整指南（国内加速版）

​适用场景​：国内网络环境下，Playwright 安装 Chromium 速度慢、镜像源 404、版本不匹配等问题
​系统环境​：Windows 10/11 + PowerShell + Node.js
​最后更新​：2026年3月12日

📋 目录

1. 问题背景
2. 核心原理
3. 方案对比
4. 方案一：手动下载 + 缓存目录安装（推荐）
5. 方案二：使用 executablePath 指定路径（灵活）
6. 方案三：代理 + 官方源下载
7. 版本匹配与兼容性
8. 常见问题排查
9. 附：一键脚本合集

🔍 问题背景

在国内使用 Playwright 时，执行 npx playwright install chromium 经常遇到：

❌ 下载速度极慢（< 50KB/s）
❌ 镜像源 404：NoSuchKey - The specified key does not exist
❌ 版本不匹配：本地文件被 --force 参数误删

​根本原因​​：

• Playwright 默认从 playwright.azureedge.net 下载，国内访问慢
• 国内镜像（如 npmmirror）同步有延迟，新版本可能缺失
• Playwright 对目录结构和版本号校验严格，手动放置容易出错

⚙️ 核心原理

Playwright 安装浏览器的流程：

1. 读取当前 Playwright 版本 → 确定需要的 Chromium revision（如 v1208）
2. 检查本地缓存目录：~/.cache/ms-playwright/chromium-<revision>/
3. 如果存在且结构正确 → 跳过下载
4. 如果不存在 → 从配置源下载 → 解压到缓存目录

​关键路径​：

缓存根目录: C:\Users\<用户名>\.cache\ms-playwright\
版本目录:   chromium-1208/          ← revision 必须匹配
浏览器目录: chrome-win/             ← 必须是这个名称（不是 chrome-win64!）
可执行文件: chrome-win/chrome.exe   ← 最终入口

📊 方案对比

💡 推荐优先尝试 ​方案一​，失败再用 方案二 保底

🎯 方案一：手动下载 + 缓存目录安装（推荐）

步骤 1：确认需要的 Chromium 版本

# 查看 Playwright 需要的 Chromium revision
npx playwright install --dry-run chromium

输出示例：

Chromium 1208 (145.0.7632.6)

📝 记录版本号或者下载链接：1208 和下载版本 145.0.7632.6

步骤 2：手动下载 Chromium 压缩包

方式 A：官方源（需代理）

https://cdn.playwright.dev/builds/cft/145.0.7632.6/win64/chrome-win64.zip

方式 B：国内镜像（可能缺失新版本）

https://npmmirror.com/mirrors/playwright/builds/cft/145.0.7632.6/win64/chrome-win64.zip

💡 建议：复制链接到 浏览器 或 IDM/Motrix 下载，支持断点续传

步骤 3：创建正确的目录结构

# === 配置变量（按需修改） ===
$CACHE_ROOT = "C:\Users\herbert\.cache\ms-playwright"
$REVISION = "chromium-1208"           # ← 注意：是 1208 不是 1200，按照刚才查询的来
$ZIP_PATH = "C:\Users\herbert\Downloads\chrome-win64.zip"
$TEMP_EXTRACT = "C:\Temp\chromium-temp"

# === 1. 创建版本目录 ===
mkdir -p "$CACHE_ROOT\$REVISION"

# === 2. 解压 ZIP 到临时目录 ===
Expand-Archive -Path $ZIP_PATH -DestinationPath $TEMP_EXTRACT -Force

# === 3. 重命名并移动到缓存目录 ===
# 解压后通常是 chrome-win64/，Playwright 要求是 chrome-win/
$extracted = Get-ChildItem $TEMP_EXTRACT | Select-Object -First 1
Move-Item "$($extracted.FullName)" "$CACHE_ROOT\$REVISION\chrome-win" -Force

# === 4. 清理临时文件 ===
Remove-Item $TEMP_EXTRACT -Recurse -Force

# === 5. 验证结构 ===
Write-Host "✅ 检查文件:" -ForegroundColor Green
dir "$CACHE_ROOT\$REVISION\chrome-win\chrome.exe"

✅ 最终结构应为：

C:\Users\herbert\.cache\ms-playwright\
└── chromium-1208/
    └── chrome-win/
        ├── chrome.exe          ← 必须存在
        ├── chrome.dll
        ├── resources/
        └── ...

步骤 4：让 Playwright 识别本地文件

# ❌ 不要用 --force（会删除本地文件重新下载！）
# ✅ 直接运行，自动检测本地缓存
npx playwright install chromium

🎉 成功输出：

✔ Chromium 1208 is already installed.

步骤 5：验证安装

# 启动浏览器测试
npx playwright show-browser chromium

# 或运行简单测试
npx playwright test --project=chromium --headed

🎯 方案二：使用 executablePath 指定路径（灵活）

如果不想折腾缓存目录，可直接指定 Chromium 路径。

步骤 1：解压到任意位置

$INSTALL_DIR = "C:\PlaywrightBrowsers\chromium-1208"
$ZIP_PATH = "C:\Users\herbert\Downloads\chrome-win64.zip"

mkdir -p $INSTALL_DIR
Expand-Archive -Path $ZIP_PATH -DestinationPath $INSTALL_DIR -Force

# 确认 chrome.exe 路径（通常是 chrome-win64/chrome.exe）
$CHROME_PATH = "$INSTALL_DIR\chrome-win64\chrome.exe"
Write-Host "✅ Chrome 路径: $CHROME_PATH"

步骤 2：配置 playwright.config.ts

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  use: {
    // 👇 关键：指定本地 Chromium 路径
    executablePath: 'C:\\PlaywrightBrowsers\\chromium-1208\\chrome-win64\\chrome.exe',
    
    // 可选：添加启动参数避免沙箱/权限问题
    args: [
      '--no-sandbox',
      '--disable-dev-shm-usage',
      '--disable-setuid-sandbox'
    ],
    
    // 其他常规配置
    headless: false,
    viewport: { width: 1280, height: 720 },
  },
  
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

步骤 3：跳过浏览器下载并运行

# 设置环境变量跳过自动下载
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

# 直接运行测试
npx playwright test

# 或启动交互式模式
npx playwright codegen --project=chromium

✅ 优点：完全绕过 Playwright 的版本校验和下载逻辑
⚠️ 注意：需确保 Chromium 版本与 Playwright 核心库兼容

🎯 方案三：代理 + 官方源自动下载

如果有稳定代理，可让 Playwright 自动完成下载。

步骤 1：配置代理环境变量

# 临时设置（当前会话）
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"

# 永久设置（系统环境变量）
# 控制面板 → 系统 → 高级系统设置 → 环境变量 → 新建用户变量

步骤 2：清除镜像配置（切换回官方源）

# 移除可能设置的镜像变量
Remove-Item Env:\PLAYWRIGHT_DOWNLOAD_HOST -ErrorAction SilentlyContinue

# 可选：清除旧缓存（谨慎操作）
# Remove-Item "C:\Users\herbert\.cache\ms-playwright\chromium-*" -Recurse -Force

步骤 3：执行安装

# 安装 Chromium（会走代理下载）
npx playwright install chromium

# 验证
npx playwright show-browser chromium

🔢 版本匹配与兼容性

如何查看版本对应关系？

# 1. 查看 Playwright 版本
npm list @playwright/test

# 2. 查看需要的 Chromium revision
npx playwright install --dry-run chromium

# 3. 对照官方发布说明
# 👉 https://github.com/microsoft/playwright/releases

常见版本对照表

💡 如果镜像缺失新版本，建议：

1. 使用 executablePath 方案
2. 或暂时降级 Playwright：npm install -D @playwright/test@1.42.1

🛠️ 常见问题排查

❌ 问题 1：目录结构错误，提示 "Browser is not installed"

# 检查实际结构
dir "C:\Users\herbert\.cache\ms-playwright\chromium-1208\"

# 错误示例：
# ❌ chromium-1208/chrome-win64/chrome.exe
# ✅ 应为：chromium-1208/chrome-win/chrome.exe

# 修复：重命名文件夹
ren "C:\Users\herbert\.cache\ms-playwright\chromium-1208\chrome-win64" "chrome-win"

❌ 问题 2：启动报错 "Protocol error (Target.setAutoAttach)"

原因：Chromium 版本与 Playwright 核心库不兼容

解决方案：
1. 确认版本匹配（见上方版本对照表）
2. 或使用 executablePath + 相同版本的 playwright-core
3. 或升级/降级 Playwright 到匹配版本

❌ 问题 3：缺少 DLL 依赖，启动失败

错误示例：
❌ The code execution cannot proceed because VCRUNTIME140_1.dll was not found.

解决方案：
1. 下载并安装 Visual C++ Redistributable：
   👉 https://aka.ms/vs/17/release/vc_redist.x64.exe
2. 重启终端后重试

❌ 问题 4：权限错误 / 访问被拒绝

# 以管理员身份运行 PowerShell
# 或修改缓存目录权限：

$CACHE_PATH = "C:\Users\herbert\.cache\ms-playwright"
icacls $CACHE_PATH /grant "$($env:USERNAME):F" /T

❌ 问题 5：--force 参数误删本地文件

⚠️ 重要：安装本地文件时，绝对不要加 --force！

错误命令：
❌ npx playwright install chromium --force  # 会删除本地文件重新下载

正确命令：
✅ npx playwright install chromium          # 自动检测本地缓存

📦 附：一键脚本合集

脚本 1：手动安装到缓存目录（install-local.ps1）

<#
.SYNOPSIS
    手动安装 Playwright Chromium 到本地缓存目录
#>

param(
    [string]$ZipPath = "C:\Users\herbert\Downloads\chrome-win64.zip",
    [string]$Revision = "chromium-1208",
    [string]$CacheRoot = "C:\Users\herbert\.cache\ms-playwright"
)

$ErrorActionPreference = "Stop"

Write-Host "🚀 开始安装 Chromium $Revision..." -ForegroundColor Cyan

# 1. 创建目录
$targetDir = "$CacheRoot\$Revision\chrome-win"
if (Test-Path $targetDir) {
    Write-Host "⚠️  目录已存在，跳过创建" -ForegroundColor Yellow
} else {
    mkdir -p "$CacheRoot\$Revision" | Out-Null
}

# 2. 解压
$tempDir = "C:\Temp\chromium-extract-$(Get-Random)"
mkdir -p $tempDir | Out-Null
Write-Host "📦 解压文件..." -ForegroundColor Cyan
Expand-Archive -Path $ZipPath -DestinationPath $tempDir -Force

# 3. 移动并重命名
$extracted = Get-ChildItem $tempDir | Select-Object -First 1
Write-Host "🔧 移动文件到缓存目录..." -ForegroundColor Cyan
Move-Item "$($extracted.FullName)" $targetDir -Force

# 4. 清理
Remove-Item $tempDir -Recurse -Force

# 5. 验证
$chromeExe = "$targetDir\chrome.exe"
if (Test-Path $chromeExe) {
    $size = (Get-Item $chromeExe).Length / 1MB
    Write-Host "✅ 安装成功!" -ForegroundColor Green
    Write-Host "   路径: $chromeExe"
    Write-Host "   大小: $($size.ToString('F1')) MB"
    
    Write-Host "`n🔄 验证 Playwright 识别..." -ForegroundColor Cyan
    npx playwright install chromium
} else {
    Write-Host "❌ 安装失败: 找不到 $chromeExe" -ForegroundColor Red
    exit 1
}

​使用​：

.\install-local.ps1 -ZipPath "C:\Downloads\chrome-win64.zip" -Revision "chromium-1208"

脚本 2：验证本地 Chromium（verify-local.js）

// verify-local.js
const { chromium } = require('playwright');

// 👇 修改为你的实际路径
const CHROME_PATH = 'C:\\Users\\herbert\\.cache\\ms-playwright\\chromium-1208\\chrome-win\\chrome.exe';

(async () => {
  console.log('🚀 启动本地 Chromium...');
  
  const browser = await chromium.launch({
    executablePath: CHROME_PATH,
    headless: false,
    args: ['--no-sandbox', '--disable-dev-shm-usage']
  });
  
  const page = await browser.newPage();
  await page.goto('https://example.com');
  
  const title = await page.title();
  console.log(`✅ 成功! 页面标题: "${title}"`);
  
  await browser.close();
})().catch(err => {
  console.error('❌ 错误:', err.message);
  process.exit(1);
});

​使用​：

node verify-local.js

脚本 3：切换代理 + 官方源下载（use-proxy.ps1）

<#
.SYNOPSIS
    临时切换代理并下载 Playwright Chromium
#>

param(
    [string]$ProxyUrl = "http://127.0.0.1:7890",
    [string]$Browser = "chromium"
)

Write-Host "🔧 配置代理: $ProxyUrl" -ForegroundColor Cyan

# 设置代理
$env:HTTPS_PROXY = $ProxyUrl
$env:HTTP_PROXY = $ProxyUrl

# 清除镜像配置（切换回官方源）
Remove-Item Env:\PLAYWRIGHT_DOWNLOAD_HOST -ErrorAction SilentlyContinue

Write-Host "📥 开始下载 $Browser..." -ForegroundColor Cyan
npx playwright install $Browser

# 清理代理变量（可选）
# Remove-Item Env:\HTTPS_PROXY, Env:\HTTP_PROXY -ErrorAction SilentlyContinue

Write-Host "✅ 完成!" -ForegroundColor Green

​使用​：

.\use-proxy.ps1 -ProxyUrl "http://127.0.0.1:7890"

📌 总结

​核心要点​：

1. ✅ 目录结构必须正确：chromium-<revision>/chrome-win/chrome.exe
2. ✅ 安装时不要加 --force，避免误删本地文件
3. ✅ 版本要匹配：Playwright 版本 ↔ Chromium revision
4. ✅ 缺少 DLL？安装 VC++ Redistributable

💬 遇到问题？

1. 检查目录结构：dir C:\Users\<你>\.cache\ms-playwright\chromium-xxx\
2. 确认 chrome.exe 存在且可执行
3. 查看 Playwright 版本：npm list @playwright/test
4. 对照官方发布：https://github.com/microsoft/playwright/releases

欢迎在评论区留言交流！👇

本文同步发布于：[你的博客链接]
转载请注明出处