Playwright Chromium 安装避坑指南 (Windows 国内环境)

📝 Playwright Chromium 安装避坑指南 (Windows 国内环境)

日期: 2026-03-25
环境: Windows 11 + Node.js + 国内网络
核心问题: 版本不匹配、镜像源缺失、网络超时

---

🚨 问题回顾：典型的“三步死循环”

在本次安装过程中，我们遇到了国内用户最典型的三个坑：

阶段	错误现象	根本原因
1. 初始化	Project(s) "chromium" not found	在系统目录 (system32) 运行，缺少配置文件。
2. 下载	Executable doesn't exist ... chromium-1208	版本错位：项目默认安装最新版 (v1208)，但国内镜像源该版本的 headless-shell 组件缺失 (404)，导致下载不完整。
3. 运行	net::ERR_ABORTED / Target page closed	网络拦截：浏览器启动成功，但示例代码访问的 playwright.dev (国外站) 被墙或超时。

---

✅ 最终解决方案：精准版本降级法

与其死磕下载缺失的最新组件，不如让软件版本迁就已成功下载的旧版浏览器。

第一步：清理环境与目录

不要在 C:\Windows\System32 下操作！建立独立工作区。

mkdir C:\Users\aku\my-playwright-test
cd C:\Users\aku\my-playwright-test

第二步：安装“黄金版本” (Playwright 1.48.0)

经过验证，Playwright 1.48.0 对应的 Chromium v1148 在国内镜像源完整且稳定。

:: 1. 初始化项目 (选择 TypeScript, 不下载浏览器)
npm init playwright@latest
:: (交互时：Install browsers? 选 No)

:: 2. 强制降级到 1.48.0
npm uninstall @playwright/test playwright
npm install @playwright/test@1.48.0

第三步：配置镜像并下载浏览器

使用淘宝镜像下载完整的 v1148 版本。

:: 设置镜像环境变量
set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright

:: 仅安装 chromium
npx playwright install chromium

关键检查点：确保终端输出显示 playwright build v1148。如果显示其他版本号，请重复第二步清理 node_modules。

第四步：修改测试用例 (避开国外网站)

默认的 example.spec.ts 访问的是国外官网，国内必挂。请替换为国内站点。

文件: tests/example.spec.ts

import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://www.baidu.com'); // 改为百度
  await expect(page).toHaveTitle(/百度/);
});

test('search test', async ({ page }) => {
  await page.goto('https://www.baidu.com');
  await page.fill('#kw', 'Playwright');
  await page.press('#kw', 'Enter');
  await page.waitForURL(/wd=Playwright/);
  await expect(page.locator('#content_left')).toBeVisible();
});

第五步：运行验证

npx playwright test --project=chromium --headed

✅ 成功标志：浏览器弹出，自动搜索，终端显示 2 passed。

---

💡 核心知识点总结

1. 版本对应关系 (Version Mapping)

Playwright 的核心库版本与浏览器二进制版本是严格绑定的，不能混用。

• @playwright/test@1.50.0 ➔ 需要 chromium-12xx (国内镜像可能缺失)
• @playwright/test@1.48.0 ➔ 需要 chromium-1148 (推荐, 国内镜像完整)
• @playwright/test@1.46.0 ➔ 需要 chromium-1140

经验法则：如果遇到 headless-shell 404 错误，不要尝试修复网络，直接降级 Playwright 版本到 1.48.0 是最快的解决路径。

2. 目录规范

• ❌ 禁止在 C:\Windows\System32 或任何系统目录下运行 npm init。
• ✅ 必须在用户目录或专门的项目文件夹中操作，否则会导致权限问题和配置读取失败。

3. 网络策略

• 下载阶段：必须使用镜像源 (npmmirror.com)。
• 运行阶段：测试脚本避免直接访问 playwright.dev, google.com 等国外站点，除非你有稳定的代理环境。建议使用 baidu.com, bing.com (CN) 作为冒烟测试目标。

4. 常用命令速查

:: 查看当前安装的 Playwright 版本
npm list @playwright/test

:: 查看本地已下载的浏览器版本
dir C:\Users\%USERNAME%\AppData\Local\ms-playwright

:: 清除所有浏览器缓存 (用于重置环境)
rmdir /s /q "C:\Users\%USERNAME%\AppData\Local\ms-playwright"

---

🎉 结语

本次安装历程证明，在国内网络环境下，“版本降级”比“网络修复”更高效。只要锁定 Playwright 1.48.0 + Chromium v1148 这一组合，即可绕过镜像源缺失问题，快速搭建可用的自动化测试环境。

📌最新补充

我在cmd窗口执行playwright codegen www.baidu.com的时候,仍会提示报错需要V1208的chromium,实际上我前面已经安装了playwright 1.58的版本,并安装了对应的v1140的chromium,最后我的解决办法如下:

1.将1140的chromium文件夹复制一份,修改文件夹的名字为chromium-1208

2.使用迅雷手动下载chromium-1208并解压,将其放入chromium-1208文件夹下

3.再次在cmd窗口中,执行playwright codegen www.baidu.com,可以正常进入录制模式