安装浏览器与系统依赖

为什么浏览器要单独装

Playwright 的包本身不含浏览器。

原因很实在：三套内核加起来好几百 MB，塞进 npm 包不现实。所以装完 @playwright/test 之后，还要用 CLI 单独把浏览器二进制拉下来。

更关键的一点：每个 Playwright 版本绑定特定版本的浏览器。1.62.x 配的是它那一代的 Chromium、Firefox、WebKit，引擎版本随 Playwright 版本升级。

所以规矩就一条：升了 Playwright，就重新跑一次 install。

两条核心命令

install：下载浏览器

不带参数就装默认的全套：

npx playwright install

只想装某一个：

npx playwright install webkit

装多个，空格分隔：

npx playwright install chromium webkit

想知道到底支持哪些，看帮助：

npx playwright install --help

install-deps：安装系统依赖

浏览器不是有个可执行文件就能跑。它依赖一堆系统库 —— 字体、音视频编解码、图形渲染。

桌面系统一般都有，干净的 Linux 容器基本都没有。这就是为什么本地跑得好好的，一上 CI 就报「找不到某个 .so 文件」。

解决办法：

npx playwright install-deps

也能只装某个浏览器的依赖：

npx playwright install-deps chromium

合起来一步到位

CI 上最常用的写法，浏览器和依赖一起装：

npx playwright install --with-deps chromium

三套内核分别是什么来头

这块搞清楚，选型时不会犯迷糊。

Chromium

Playwright 默认用的是开源 Chromium 构建，不是品牌版 Google Chrome。

Chromium 项目本身跑在品牌浏览器前面。当外界都在用 Chrome N 的时候，Playwright 已经支持 Chromium N+1 —— 那是几周后才会推给 Chrome 和 Edge 用户的版本。

这其实是个优势：你能提前发现兼容问题，有充足时间修。

Firefox

Playwright 的 Firefox 跟当前 Firefox Stable 版本对齐。

注意：它不能驱动你机器上装的品牌版 Firefox。Playwright 用的是打过补丁的构建，品牌版没有这些补丁。

WebKit

WebKit 取自 WebKit 主干分支的较新源码，通常跑在 Apple Safari 前面。

同样地，它不能驱动品牌版 Safari。

headless shell：装小一点

Chromium 这边有个细节值得知道。

Playwright 分发两个东西：完整 Chromium（有头模式用）和一个独立的 chromium headless shell（无头模式用）。

如果你只在无头模式下跑测试，比如典型的 CI 场景，而且没有指定 channel 选项，那完整 Chromium 根本用不上。可以只装 shell，省下不少下载时间和磁盘：

npx playwright install --with-deps --only-shell

反过来，如果你想用新版无头模式（把 channel 设成 'chromium'），走的是真实 Chrome 内核，那 headless shell 就多余了，可以跳过：

npx playwright install --with-deps --no-shell

新版无头模式更接近真实浏览器行为，官方的说法是「更真实、更可靠、功能更全」，适合对准确度要求高的端到端测试和扩展测试。

配置写法：

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

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], channel: 'chromium' },
    },
  ],
});

用品牌版 Chrome / Edge

Playwright 也能驱动机器上已装的 Google Chrome 和 Microsoft Edge，支持 Stable 和 Beta 通道。

在配置里通过 channel 指定：

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

export default defineConfig({
  projects: [
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' },
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' },
    },
  ],
});

可选的通道值：chrome、msedge、chrome-beta、msedge-beta、chrome-dev、msedge-dev、chrome-canary、msedge-canary。

机器上没装？可以让 Playwright 装：

npx playwright install msedge

什么时候该切品牌版

• 默认情况：用打包的 Chromium 就好，能提前发现问题。
• 回归测试有硬性要求：有些测试规范要求必须在公开发布的浏览器上验证，那就切 chrome 或 msedge。
• 依赖媒体编解码：Chromium 因为授权原因不含全部编解码器。如果你的页面用到这类能力（少见），得用官方版本。
• 企业策略环境：品牌浏览器会遵守企业策略 —— 功能限制、代理、强制扩展，这些都会干扰测试。这种环境下本地用打包 Chromium，CI 机器上再切品牌版。

内网、代理与镜像

企业内网经常挡外部下载。Playwright 提供了几个环境变量。

走代理

HTTPS_PROXY=https://192.0.2.1 npx playwright install

Windows PowerShell：

$Env:HTTPS_PROXY="https://192.0.2.1"
npx playwright install

如果代理用了自签名证书，报 Error: self signed certificate in certificate chain，得先指定根证书：

export NODE_EXTRA_CA_CERTS="/path/to/cert.pem"

Linux 上装系统依赖还要走代理的话，必须以 root 执行，否则环境变量传不进包管理器：

sudo HTTPS_PROXY=https://192.0.2.1 npx playwright install-deps

网络慢就调大超时

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

从内部制品库下载

公司自建了浏览器二进制镜像的话：

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

还能按浏览器分别指定，这几个变量优先级高于上面那个：

• PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST
• PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST
• PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST

浏览器装到哪去了

不在 node_modules 里，在系统缓存目录：

• Windows：%USERPROFILE%\AppData\Local\ms-playwright
• macOS：~/Library/Caches/ms-playwright
• Linux：~/.cache/ms-playwright

占用大概是这个量级：Chromium 约 281 MB、Firefox 约 187 MB、WebKit 约 180 MB。这几个数字随版本浮动，心里有个几百 MB 的概念就行。

放缓存目录的好处是多个项目共享一份，不用每个项目下一遍。

改到别处

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

注意：跑测试的时候也要设同一个变量，否则 Playwright 找不到：

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

想固定下来，就写进 .bashrc。

装到项目本地

设成 0 会放进 node_modules/playwright-core/.local-browsers：

PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

旧版本会自动清理

Playwright 记录着哪些客户端在用哪个版本的浏览器。当某个版本不再有人用，它会自动删掉，不会一直堆着占磁盘。

不想让它自动清理，设 PLAYWRIGHT_SKIP_BROWSER_GC=1。

查看和卸载

看看机器上装了些什么：

npx playwright install --list

卸载当前 Playwright 安装对应的浏览器：

npx playwright uninstall

想连其他 Playwright 安装的浏览器一起清掉：

npx playwright uninstall --all

CI 上的实用建议

1. 缓存浏览器目录。把 ~/.cache/ms-playwright 加进 CI 缓存，缓存键带上 Playwright 版本号。省下每次几百 MB 的下载。
2. 只装用到的浏览器。如果 CI 只跑 Chromium，就写 npx playwright install --with-deps chromium，别全装。
3. 无头场景加 --only-shell。前提是没用 channel。
4. 用官方 Docker 镜像。系统依赖都预装好了，直接省掉 install-deps 这一步和它带来的一堆麻烦。

小结

install 管浏览器，install-deps 管系统库，--with-deps 一次搞定。

三套内核都是 Playwright 自己打包的，跟你机器上的品牌浏览器不是一回事。想用品牌版就设 channel。

内网环境靠环境变量解决下载问题，CI 上靠缓存和精简安装提速。

下一章开始写代码 —— 我们跑通第一个测试。