跳到主要内容

浏览器

简介​

每个版本的 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()) {
      // 启动 Chromium、Firefox 或 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 已经支持几周后将在 Google Chrome 和 Microsoft Edge 中发布的 Chromium N+1 版本。

Chromium：无头壳子​

Playwright 提供了用于有头模式操作的常规 Chromium 版本，以及用于无头模式的单独 Chromium 无头壳子。

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

# 仅以无头模式运行测试
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 选项跳过下载无头壳子：

# 仅以无头模式运行测试
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --no-shell"

谷歌 Chrome 浏览器与微软 Edge 浏览器​

虽然 Playwright 可以下载并使用最新的 Chromium 版本，但它也可以与计算机上已安装的谷歌 Chrome 浏览器和微软 Edge 浏览器配合使用（请注意，Playwright 默认不会安装这些浏览器）。具体而言，当前的 Playwright 版本将支持这些浏览器的稳定版和测试版渠道。

可用的渠道有 chrome、msedge、chrome-beta、msedge-beta、chrome-dev、msedge-dev、chrome-canary、msedge-canary。

注意

某些企业浏览器策略可能会影响 Playwright 启动和控制谷歌 Chrome 浏览器与微软 Edge 浏览器的能力。在有浏览器策略的环境中运行不在 Playwright 项目的支持范围内。

注意

谷歌 Chrome 浏览器和微软 Edge 浏览器已切换到 新的无头模式 实现方式，该方式更接近常规的有头模式。这与 Playwright 在无头模式下默认使用的 Chromium 无头外壳 不同，因此在某些情况下可能会有不同的行为。详情请参阅 问题 #33566。

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      // 渠道可以是 "chrome"、"msedge"、"chrome-beta"、"msedge-beta" 或 "msedge-dev"。
      Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("msedge"));
      Page page = browser.newPage();
      // ...
    }
  }
}

安装谷歌浏览器（Google Chrome）和微软 Edge 浏览器​

如果您的计算机上没有安装谷歌浏览器（Google Chrome）或微软 Edge 浏览器，可以使用 Playwright 命令行工具进行安装：

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

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

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

何时使用以及何时不使用谷歌浏览器（Google Chrome）和微软 Edge 浏览器？​

默认设置​

大多数情况下，使用默认的 Playwright 配置以及最新的 Chromium 是个不错的选择。由于 Playwright 版本领先于浏览器的稳定版本通道，这能让您放心，即将发布的谷歌浏览器（Google Chrome）或微软 Edge 浏览器版本不会导致您的网站出现问题。您可以提前发现问题，并在 Chrome 正式更新之前有足够的时间进行修复。

回归测试​

话虽如此，测试策略通常要求针对当前公开可用的浏览器进行回归测试。在这种情况下，您可以选择使用其中一个稳定版本通道，即 "chrome" 或 "msedge"。

媒体编解码器​

使用官方二进制文件进行测试的另一个原因是测试与媒体编解码器相关的功能。由于各种许可考虑和协议，Chromium 并不具备谷歌浏览器（Google Chrome）或微软 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 持续集成环境中运行 WebKit 通常是最经济实惠的选择，但为了获得最接近 Safari 的体验，你应该在 Mac 上运行 WebKit，例如在进行视频播放测试时。

在防火墙或代理后安装​

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

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

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 环境变量设置自定义根证书：

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

如果连接到 Playwright 浏览器存档的网络速度较慢，可以使用 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT 环境变量以毫秒为单位增加连接超时时间：

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 会从微软的 CDN 下载浏览器。

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

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。

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"

管理浏览器二进制文件​

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 时，指定将浏览器下载到特定位置：

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

在运行 Playwright 脚本时，指定在共享位置搜索浏览器。

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn test

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

备注

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

跳过浏览器下载​

在某些情况下，由于浏览器二进制文件是单独管理的，因此希望完全避免下载浏览器。 这可以通过在安装前设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 变量来实现。

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test

陈旧浏览器的移除​

Playwright 会跟踪使用其浏览器的客户端。当不再有客户端需要特定版本的浏览器时，该版本将从系统中删除。这样，你可以安全地使用不同版本的 Playwright 实例，同时，不会为不再使用的浏览器浪费磁盘空间。 若要选择不进行未使用浏览器的移除操作，可以设置环境变量 PLAYWRIGHT_SKIP_BROWSER_GC=1。

卸载浏览器​

这将移除当前 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"