浏览器

简介

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

每次发布新版本时，Playwright 会更新其支持的浏览器版本，因此最新版的 Playwright 总是支持最新的浏览器。这意味着每次更新 Playwright 时，可能都需要重新运行 install CLI 命令。

安装浏览器

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

playwright install

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

playwright install webkit

查看所有支持的浏览器：

playwright install --help

安装系统依赖

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

playwright install-deps

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

playwright install-deps chromium

你也可以将 install-deps 与 install 结合使用，以便一次性安装浏览器和操作系统依赖。

playwright install --with-deps chromium

有关官方支持的操作系统的详细信息，请参阅系统要求。

配置浏览器

Playwright 可以在 Chromium、WebKit 和 Firefox 浏览器以及 Google Chrome 和 Microsoft Edge 等品牌浏览器上运行测试，也可以在模拟的平板电脑和移动设备上运行。有关选定桌面、平板电脑和移动设备的完整参数列表，请参阅设备参数注册表。

在不同浏览器上运行测试

在特定浏览器上运行测试：

pytest test_login.py --browser webkit

在多个浏览器上运行测试：

pytest test_login.py --browser webkit --browser firefox

在移动视口上测试：

pytest test_login.py --device="iPhone 13"

在品牌浏览器上测试：

pytest test_login.py --browser-channel msedge

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 无头 shell 用于无头模式。

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

# 只在无头模式下运行测试
playwright install --with-deps --only-shell

Chromium：新无头模式

你可以通过使用 'chromium' 通道选择新无头模式。正如官方 Chrome 文档所述：

新无头模式实际上是真正的 Chrome 浏览器，因此更加真实、可靠，并提供更多功能。这使其更适合高精度的端到端 Web 应用程序测试或浏览器扩展测试。

请参阅 issue #33566 了解详情。

pytest test_login.py --browser-channel chromium

使用新无头模式时，可以通过使用 --no-shell 选项跳过下载无头 shell：

# 只在无头模式下运行测试
playwright install --with-deps --no-shell

Google Chrome & Microsoft Edge

虽然 Playwright 可以下载并使用最近的 Chromium 构建，但它可以在机器上操作可用的品牌 Google Chrome 和 Microsoft Edge 浏览器（请注意，Playwright 默认不会安装它们）。特别是，当前的 Playwright 版本将支持这些浏览器的 Stable 和 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 了解详情。

pytest test_login.py --browser-channel msedge

或者在直接使用库时，你可以在启动浏览器时指定 channel 参数：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # 渠道可以是 "chrome"、"msedge"、"chrome-beta"、"msedge-beta" 或 "msedge-dev"。
    browser = p.chromium.launch(channel="msedge")
    page = browser.new_page()
    page.goto("https://playwright.dev")
    print(page.title())
    browser.close()

安装 Google Chrome & Microsoft Edge

如果 Google Chrome 或 Microsoft Edge 在你的机器上不可用，你可以使用 Playwright 命令行工具安装它们：

playwright install msedge

注意

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

使用 --help 选项运行命令以查看可安装浏览器的完整列表。

何时使用 Google Chrome & Microsoft Edge 以及何时不使用？

默认设置

使用带有最新 Chromium 的默认 Playwright 配置通常是个好主意。由于 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 从 Microsoft 的 CDN 下载浏览器。

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

Bash
PowerShell
Batch

pip install playwright
HTTPS_PROXY=https://192.0.2.1 playwright install

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

set HTTPS_PROXY=https://192.0.2.1
pip install playwright
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

pip install playwright
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 playwright install

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
pip install playwright
playwright install

set PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
pip install playwright
playwright install

如果你正在安装依赖项并且需要在 Linux 上使用代理，请确保以 root 用户身份运行命令。否则，Playwright 将尝试成为 root 并不会将环境变量如 HTTPS_PROXY 传递给 Linux 包管理器。

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

从工件仓库下载

默认情况下，Playwright 从 Microsoft 的 CDN 下载浏览器。

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

Bash
PowerShell
Batch

pip install playwright
PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 playwright install

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

set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
pip install playwright
playwright install

你也可以使用特定浏览器的下载主机，使用 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 环境变量，这些变量优先于 PLAYWRIGHT_DOWNLOAD_HOST。

Bash
PowerShell
Batch

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

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

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

管理浏览器二进制文件

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

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

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

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

你可以使用环境变量覆盖默认行为。安装 Playwright 时，要求它将浏览器下载到特定位置：

Bash
PowerShell
Batch

pip install playwright
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install

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

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

运行 Playwright 脚本时，要求它在共享位置搜索浏览器。

Bash
PowerShell
Batch

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.py

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
python playwright_script.py

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
python playwright_script.py

Playwright 会跟踪需要这些浏览器的包，并在更新 Playwright 到新版本时垃圾回收它们。

备注

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

过时浏览器删除

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

要选择退出未使用浏览器的删除，请设置 PLAYWRIGHT_SKIP_BROWSER_GC=1 环境变量。

卸载浏览器

这将删除当前 Playwright 安装的浏览器（chromium、firefox、webkit）：

playwright uninstall

要同时删除其他 Playwright 安装的浏览器，请传递 --all 参数：

playwright uninstall --all

简介​

安装浏览器​

安装系统依赖​

配置浏览器​

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

Chromium​

Chromium：无头 shell​

Chromium：新无头模式​

Google Chrome & Microsoft Edge​

安装 Google Chrome & Microsoft Edge​

何时使用 Google Chrome & Microsoft Edge 以及何时不使用？​

默认设置​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理后面安装​

从工件仓库下载​

管理浏览器二进制文件​

过时浏览器删除​

卸载浏览器​

简介