浏览器

简介

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

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

安装浏览器

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install webkit"

查看所有支持的浏览器

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --help"

安装系统依赖项

系统依赖项可以自动安装。这对于 CI 环境很有用。

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps"

您也可以通过将单个浏览器作为参数传递来安装其依赖项

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps chromium"

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps chromium"

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

配置浏览器

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

在不同浏览器上运行测试

在特定浏览器上运行测试

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      // Launch chromium, firefox or webkit.
      Browser browser = playwright.chromium().launch();
      Page page = browser.newPage();
      // ...
    }
  }
}

在多个浏览器上运行测试，并使其基于环境变量 BROWSER

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = null;
      String browserName = System.getenv("BROWSER");
      if (browserName.equals("chromium")) {
        browser = playwright.chromium().launch();
      } else if (browserName.equals("firefox")) {
        browser = playwright.firefox().launch();
      } else if (browserName.equals("webkit")) {
        browser = playwright.webkit().launch();
      }
      Page page = browser.newPage();
      // ...
    }
  }
}

Chromium

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

Chromium：无头 shell

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

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

# only running tests headlessly
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --only-shell"

Chromium：新的无头模式

您可以使用 `'chromium'` 通道选择加入新的无头模式。正如 Chrome 官方文档所述

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

有关详细信息，请参阅问题 #33566。

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("chromium"));
      Page page = browser.newPage();
      // ...
    }
  }
}

使用新的无头模式，您可以在浏览器安装期间使用 --no-shell 选项跳过下载无头 shell

# only running tests headlessly
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --no-shell"

Google Chrome 和 Microsoft Edge

虽然 Playwright 可以下载并使用最新的 Chromium 构建，但它可以在机器上运行已有的品牌 Google Chrome 和 Microsoft Edge 浏览器（请注意，Playwright 默认不安装它们）。特别是，当前 Playwright 版本将支持这些浏览器的稳定版和测试版通道。

可用的通道有 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 无头 shell 不同，因此在某些情况下预期会有不同的行为。有关详细信息，请参阅问题 #33566。

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      // Channel can be "chrome", "msedge", "chrome-beta", "msedge-beta" or "msedge-dev".
      Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("msedge"));
      Page page = browser.newPage();
      // ...
    }
  }
}

安装 Google Chrome 和 Microsoft Edge

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="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 从 Microsoft 的 CDN 下载浏览器。

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

Bash
PowerShell
批处理

HTTPS_PROXY=https://192.0.2.1 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:HTTPS_PROXY="https://192.0.2.1"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set HTTPS_PROXY=https://192.0.2.1
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

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

Bash
PowerShell
批处理

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
批处理

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

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

sudo HTTPS_PROXY=https://192.0.2.1 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps"

从工件仓库下载

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

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

Bash
PowerShell
批处理

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

还可以使用 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 环境变量来设置每个浏览器的下载主机，这些变量优先于 PLAYWRIGHT_DOWNLOAD_HOST。

Bash
PowerShell
批处理

PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="http://203.0.113.3"
$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3
set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

使用预安装的 Node.js

Bash
PowerShell
批处理

PLAYWRIGHT_NODEJS_PATH="/usr/local/bin/node" mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:PLAYWRIGHT_NODEJS_PATH="C:\Program Files\nodejs\node.exe"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set PLAYWRIGHT_NODEJS_PATH=C:\Program Files\nodejs\node.exe
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="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
批处理

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

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

Bash
PowerShell
批处理

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn test

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

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn test

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

注意

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

跳过浏览器下载

在某些情况下，希望完全避免浏览器下载，因为浏览器二进制文件是单独管理的。

这可以通过在安装之前设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 变量来完成。

Bash
PowerShell
批处理

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test

$Env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test

set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test

过期浏览器移除

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

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

列出所有已安装的浏览器：

打印机器上所有 Playwright 安装的浏览器列表。

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --list"

卸载浏览器

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="uninstall"

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

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="uninstall --all"

简介​

安装浏览器​

安装系统依赖项​

配置浏览器​

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

Chromium​

Chromium：无头 shell​

Chromium：新的无头模式​

Google Chrome 和 Microsoft Edge​

安装 Google Chrome 和 Microsoft Edge​

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

默认值​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理后安装​

从工件仓库下载​

使用预安装的 Node.js​

管理浏览器二进制文件​

跳过浏览器下载​

过期浏览器移除​

列出所有已安装的浏览器：​

卸载浏览器​

简介