浏览器支持

简介

每个版本的 Playwright 都需要特定版本的浏览器二进制文件才能运行。你需要使用 Playwright CLI 来安装这些浏览器。

随着每次发布，Playwright 都会更新其支持的浏览器版本，以确保最新版 Playwright 始终支持最新的浏览器。这意味着每次更新 Playwright 时，你可能需要重新运行 install CLI 命令。

安装浏览器

Playwright 可以安装支持的浏览器。不带参数运行命令将安装默认浏览器。

npx playwright install

你也可以通过提供参数来安装特定浏览器：

npx playwright install webkit

查看所有支持的浏览器：

npx playwright install --help

安装系统依赖项

系统依赖项可以自动安装。这在 CI 环境中特别有用。

npx playwright install-deps

你也可以通过传递参数为单个浏览器安装依赖项：

npx playwright install-deps chromium

还可以将 install-deps 与 install 结合使用，通过单个命令同时安装浏览器和操作系统依赖项。

npx playwright install --with-deps chromium

查看官方支持的系统要求。

定期更新 Playwright

通过保持 Playwright 版本最新，你将能够使用新功能，并在最新浏览器版本公开发布前测试你的应用程序，及时发现问题。

# 更新 playwright
npm install -D @playwright/test@latest

安装新浏览器

npx playwright install

查看 [发布说明](./release-notes.mdx) 了解最新版本信息及变更内容。

```bash
# 运行以下命令查看已安装的 Playwright 版本
npx playwright --version

配置浏览器

Playwright 可以在 Chromium、WebKit 和 Firefox 浏览器上运行测试，也支持品牌浏览器如 Google Chrome 和 Microsoft Edge。同时支持在模拟的平板和移动设备上运行。完整支持的桌面、平板和移动设备列表请参阅设备参数注册表。

在不同浏览器上运行测试

Playwright 可以通过在配置中设置 projects 来在多个浏览器和配置下运行您的测试。您还可以为每个项目添加不同的选项。

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

export default defineConfig({
  projects: [
    /* 针对桌面浏览器进行测试 */
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    /* 针对移动端视口进行测试 */
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    /* 针对品牌浏览器进行测试 */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // 或 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // 或 'msedge-dev'
    },
  ],
});

默认情况下，Playwright 会运行所有项目。

npx playwright test

Running 7 tests using 5 workers

  ✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
  ✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Safari] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Google Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Microsoft Edge] › example.spec.ts:3:1 › basic test (2s)

使用 --project 命令行选项可以运行单个项目。

npx playwright test --project=firefox

Running 1 test using 1 worker

  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)

通过 VS Code 扩展，您可以在 Playwright 侧边栏中勾选浏览器名称旁边的复选框来在不同浏览器上运行测试。这些名称在 Playwright 配置文件的 projects 部分定义。安装 Playwright 时的默认配置会提供 3 个项目：Chromium、Firefox 和 WebKit。默认会选中第一个项目。

VS Code 扩展中的项目部分

要在多个项目（浏览器）上运行测试，请通过勾选项目名称旁边的复选框来选择每个项目。

选择要运行测试的项目

Chromium

对于 Google Chrome、Microsoft Edge 及其他基于 Chromium 的浏览器，Playwright 默认使用开源的 Chromium 构建版本。由于 Chromium 项目领先于品牌浏览器，当全球还在使用 Google Chrome N 版本时，Playwright 已经支持将在几周后发布的 Google Chrome 和 Microsoft Edge 中采用的 Chromium N+1 版本。

Chromium: 无头模式专用 shell

Playwright 提供了常规 Chromium 构建用于有界面操作，以及单独的 chromium headless shell 用于无头模式。

如果仅在无头 shell 中运行测试（即未指定 channel 选项），例如在 CI 环境中，可以通过在安装时传递 --only-shell 参数来避免下载完整的 Chromium 浏览器。

# 仅以无头模式运行测试
npx playwright install --with-deps --only-shell

Chromium: 新型无头模式

您可以通过使用 'chromium' 渠道选择启用新型无头模式。正如 Chrome 官方文档所述:

新型 Headless 是真正的 Chrome 浏览器，因此更真实可靠，并提供更多功能。这使其更适合高精度的端到端 Web 应用测试或浏览器扩展测试。

详情请参阅 issue #33566。

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

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

使用新型无头模式时，可以通过 --no-shell 选项在浏览器安装过程中跳过下载无头 shell：

# 仅以无头模式运行测试
npx playwright install --with-deps --no-shell

Google Chrome 与 Microsoft Edge

虽然 Playwright 可以下载并使用最新的 Chromium 构建版本，但它也能操作机器上已安装的品牌浏览器 Google Chrome 和 Microsoft Edge（请注意 Playwright 默认不会安装这些浏览器）。具体而言，当前 Playwright 版本支持这些浏览器的稳定版和 Beta 频道。

可用的频道包括：chrome、msedge、chrome-beta、msedge-beta、chrome-dev、msedge-dev、chrome-canary、msedge-canary。

注意

某些企业浏览器策略可能会影响 Playwright 启动和控制 Google Chrome 及 Microsoft Edge 的能力。在存在浏览器策略的环境中运行已超出 Playwright 项目的支持范围。

注意

Google Chrome 和 Microsoft Edge 已切换至新的无头模式实现，该模式更接近常规的有头模式。这与 Playwright 默认在无头模式下使用的 chromium headless shell 不同，因此在某些情况下会出现行为差异。详情请参阅 issue #33566。

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

export default defineConfig({
  projects: [
    /* 针对品牌浏览器进行测试 */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // 或 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // 或 "msedge-beta" 或 'msedge-dev'
    },
  ],
});

安装 Google Chrome 和 Microsoft Edge

如果您的机器上没有安装 Google Chrome 或 Microsoft Edge，可以使用 Playwright 命令行工具进行安装：

npx playwright install msedge

注意

Google Chrome 或 Microsoft Edge 将安装在操作系统的默认全局位置，会覆盖您当前的浏览器安装。

运行时加上 --help 选项可以查看所有可安装浏览器的完整列表。

何时使用 Google Chrome 和 Microsoft Edge？何时不使用？

默认情况

大多数情况下，使用 Playwright 默认配置搭配最新版 Chromium 是个不错的选择。由于 Playwright 的版本领先于浏览器的稳定版渠道，这能确保即将发布的 Google Chrome 或 Microsoft Edge 版本不会破坏您的网站。您可以及早发现问题，并在官方 Chrome 更新前有充足时间进行修复。

回归测试

尽管如此，测试策略通常要求针对当前公开可用的浏览器进行回归测试。这种情况下，您可以选择使用稳定版渠道 "chrome" 或 "msedge"。

媒体编解码器

使用官方二进制文件进行测试的另一个原因是测试与媒体编解码器相关的功能。由于各种许可考虑和协议，Chromium 并不包含 Google Chrome 或 Microsoft Edge 捆绑的所有编解码器。如果您的网站依赖这类编解码器（这种情况很少见），您也需要使用官方渠道。

企业策略

Google Chrome 和 Microsoft Edge 遵循企业策略，这些策略包括功能限制、网络代理以及可能妨碍测试的强制扩展。因此，如果您所在的组织使用这类策略，最简单的方法是在本地测试时使用捆绑的 Chromium，而在通常没有此类限制的测试机上仍可选择稳定版渠道。

Firefox

Playwright 的 Firefox 版本与最新的 Firefox Stable 构建版本匹配。由于 Playwright 依赖于特定的补丁，因此无法与品牌版的 Firefox 一起使用。

请注意，某些高度依赖底层平台的功能在不同操作系统上可能有所差异。例如，Linux、macOS 和 Windows 之间可用的媒体编解码器存在显著差异。

WebKit

Playwright 的 WebKit 源自最新的 WebKit 主分支源代码，通常比这些更新被整合到 Apple Safari 和其他基于 WebKit 的浏览器中更早。这为应对潜在的浏览器更新问题提供了大量提前时间。由于 Playwright 依赖于特定的补丁，因此无法与品牌版的 Safari 一起使用。不过，您可以使用最新的 WebKit 构建版本进行测试。

请注意，某些高度依赖底层平台的功能在不同操作系统上可能有所差异。例如，Linux、macOS 和 Windows 之间可用的媒体编解码器存在显著差异。虽然在 Linux CI 上运行 WebKit 通常是最经济的选择，但为了获得最接近 Safari 的体验，您应该在 Mac 上运行 WebKit，例如在进行视频播放测试时。

在防火墙或代理后安装

默认情况下，Playwright 会从微软的 CDN 下载浏览器。

有时公司会维护内部代理，阻止直接访问公共资源。在这种情况下，可以配置 Playwright 通过代理服务器下载浏览器。

Bash
PowerShell
Batch

HTTPS_PROXY=https://192.0.2.1 npx playwright install

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

set HTTPS_PROXY=https://192.0.2.1
npx playwright install

如果代理请求被自定义的不可信证书颁发机构(CA)拦截，导致下载浏览器时出现 Error: self signed certificate in certificate chain 错误，必须在安装浏览器前通过 NODE_EXTRA_CA_CERTS 环境变量设置自定义根证书：

Bash
PowerShell
Batch

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

$Env:NODE_EXTRA_CA_CERTS="C:\certs\root.crt"

set NODE_EXTRA_CA_CERTS="C:\certs\root.crt"

如果您的网络连接 Playwright 浏览器归档文件较慢，可以通过 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT 环境变量增加连接超时时间（毫秒）：

Bash
PowerShell
Batch

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
npx playwright install

set PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
npx playwright install

如果您正在安装系统依赖项且需要在 Linux 上使用代理，请确保以 root 用户身份运行命令。否则，Playwright 会尝试获取 root 权限，但不会将 HTTPS_PROXY 等环境变量传递给 Linux 包管理器。

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

从制品仓库下载

默认情况下，Playwright 会从微软的 CDN 下载浏览器。

有时企业会维护一个内部制品仓库来托管浏览器二进制文件。这种情况下，可以通过设置 PLAYWRIGHT_DOWNLOAD_HOST 环境变量来配置 Playwright 从自定义位置下载。

Bash
PowerShell
Batch

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
npx playwright install

set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
npx playwright install

还可以使用针对特定浏览器的下载主机地址，通过设置 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 环境变量，这些设置会优先于 PLAYWRIGHT_DOWNLOAD_HOST。

Bash
PowerShell
Batch

PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

$Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="http://203.0.113.3"
$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
npx playwright install

set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3
set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
npx playwright install

管理浏览器二进制文件

Playwright 会将 Chromium、WebKit 和 Firefox 浏览器下载到操作系统特定的缓存文件夹中：

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

安装这些浏览器将占用几百兆的磁盘空间：

du -hs ~/Library/Caches/ms-playwright/*
281M  chromium-XXXXXX
187M  firefox-XXXX
180M  webkit-XXXX

您可以通过环境变量覆盖默认行为。在安装 Playwright 时，可以指定浏览器下载到特定位置：

Bash
PowerShell
Batch

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
npx playwright install

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright install

在运行 Playwright 脚本时，可以指定从共享位置查找浏览器：

Bash
PowerShell
Batch

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
npx playwright test

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright test

Playwright 会跟踪需要这些浏览器的软件包，并在您更新到新版本时进行垃圾回收。

备注

开发者可以通过在 .bashrc 中导出 PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers 来启用此模式。

封闭式安装

您可以选择封闭式安装方式，将浏览器二进制文件放置在本地文件夹中：

Bash
PowerShell
Batch

# 将二进制文件放置到 node_modules/playwright-core/.local-browsers
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

# 将二进制文件放置到 node_modules\playwright-core\.local-browsers
$Env:PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install

# 将二进制文件放置到 node_modules\playwright-core\.local-browsers
set PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install

:::注意

PLAYWRIGHT_BROWSERS_PATH 不会改变 Google Chrome 和 Microsoft Edge 的安装路径。 :::

清理过期浏览器

Playwright 会跟踪使用其浏览器的客户端。当没有客户端再需要特定版本的浏览器时，该版本将从系统中删除。这样您可以安全地使用不同版本的 Playwright 实例，同时不会浪费磁盘空间存储不再使用的浏览器。

要禁用未使用浏览器的自动清理功能，可以设置环境变量 PLAYWRIGHT_SKIP_BROWSER_GC=1。

卸载浏览器

以下命令将移除当前 Playwright 安装的浏览器（chromium、firefox、webkit）：

npx playwright uninstall

要同时移除其他 Playwright 安装的浏览器，可以添加 --all 参数：

npx playwright uninstall --all

简介​

安装浏览器​

安装系统依赖项​

定期更新 Playwright​

安装新浏览器

配置浏览器​

在不同浏览器上运行测试​

Chromium​

Chromium: 无头模式专用 shell​

Chromium: 新型无头模式​

Google Chrome 与 Microsoft Edge​

安装 Google Chrome 和 Microsoft Edge​

何时使用 Google Chrome 和 Microsoft Edge？何时不使用？​

默认情况​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理后安装​

从制品仓库下载​

管理浏览器二进制文件​

封闭式安装​

清理过期浏览器​

卸载浏览器​

简介