Skip to main content

浏览器

介绍​

¥Introduction

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

¥Each version of Playwright needs specific versions of browser binaries to operate. You will need to use the Playwright CLI to install these browsers.

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

¥With every release, Playwright updates the versions of the browsers it supports, so that the latest Playwright would support the latest browsers at any moment. It means that every time you update Playwright, you might need to re-run the install CLI command.

安装浏览器​

¥Install browsers

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

¥Playwright can install supported browsers. Running the command without arguments will install the default browsers.

npx playwright install

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

¥You can also install specific browsers by providing an argument:

npx playwright install webkit

查看所有支持的浏览器：

¥See all supported browsers:

npx playwright install --help

安装系统依赖​

¥Install system dependencies

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

¥System dependencies can get installed automatically. This is useful for CI environments.

npx playwright install-deps

你还可以通过将其作为参数传递来安装单个浏览器的依赖：

¥You can also install the dependencies for a single browser by passing it as an argument:

npx playwright install-deps chromium

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

¥It's also possible to combine install-deps with install so that the browsers and OS dependencies are installed with a single command.

npx playwright install --with-deps chromium

请参阅 系统要求 了解官方支持的操作系统。

¥See system requirements for officially supported operating systems.

定期更新 Playwright​

¥Update Playwright regularly

通过保持你的 Playwright 版本为最新，你将能够使用新功能并在最新的浏览器版本上测试你的应用，并在最新的浏览器版本向公众发布之前捕获故障。

¥By keeping your Playwright version up to date you will be able to use new features and test your app on the latest browser versions and catch failures before the latest browser version is released to the public.

# Update playwright
npm install -D @playwright/test@latest

# Install new browsers
npx playwright install

检查 发行说明 以了解最新版本是什么以及已发布哪些更改。

¥Check the release notes to see what the latest version is and what changes have been released.

# See what version of Playwright you have by running the following command
npx playwright --version

配置浏览器​

¥Configure Browsers

Playwright 可以在 Chromium、WebKit 和 Firefox 浏览器以及 Google Chrome 和 Microsoft Edge 等品牌浏览器上运行测试。它还可以在模拟平板电脑和移动设备上运行。请参阅 设备参数注册表，了解所选台式机、平板电脑和移动设备的完整列表。

¥Playwright can run tests on Chromium, WebKit and Firefox browsers as well as branded browsers such as Google Chrome and Microsoft Edge. It can also run on emulated tablet and mobile devices. See the registry of device parameters for a complete list of selected desktop, tablet and mobile devices.

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

¥Run tests on different browsers

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

¥Playwright can run your tests in multiple browsers and configurations by setting up projects in the config. You can also add different options for each project.

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

export default defineConfig({
  projects: [
    /* Test against desktop browsers */
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    /* Test against mobile viewports. */
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or 'msedge-dev'
    },
  ],
});

Playwright 将默认运行所有项目。

¥Playwright will run all projects by default.

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 命令行选项运行单个项目。

¥Use the --project command line option to run a single 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 配置文件的项目部分下定义。安装 Playwright 时的默认配置为你提供 3 个项目，Chromium、Firefox 和 WebKit。默认情况下选择第一个项目。

¥With the VS Code extension you can run your tests on different browsers by checking the checkbox next to the browser name in the Playwright sidebar. These names are defined in your Playwright config file under the projects section. The default config when installing Playwright gives you 3 projects, Chromium, Firefox and WebKit. The first project is selected by default.

Projects section in VS Code extension

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

¥To run tests on multiple projects(browsers), select each project by checking the checkboxes next to the project name.

Selecting projects to run tests on

Chromium​

对于 Google Chrome、Microsoft Edge 和其他基于 Chromium 的浏览器，默认情况下，Playwright 使用开源 Chromium 版本。由于 Chromium 项目领先于品牌浏览器，当世界都在使用 Google Chrome N 时，Playwright 已经支持 Chromium N+1，并将在几周后在 Google Chrome 和 Microsoft Edge 中发布。

¥For Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds. Since the Chromium project is ahead of the branded browsers, when the world is on Google Chrome N, Playwright already supports Chromium N+1 that will be released in Google Chrome and Microsoft Edge a few weeks later.

Playwright 为有头操作提供了常规的 Chromium 版本，为无头模式提供了单独的 chromium 无头外壳。有关详细信息，请参阅 问题 #33566。

¥Playwright ships a regular Chromium build for headed operations and a separate chromium headless shell for headless mode. See issue #33566 for details.

优化 CI 上的下载大小​

¥Optimize download size on CI

如果你仅在无头模式下运行测试，例如在 CI 上，你可以通过在安装期间传递 --only-shell 来避免下载常规版本的 Chromium。

¥If you are only running tests in headless mode, for example on CI, you can avoid downloading a regular version of Chromium by passing --only-shell during installation.

# only running tests headlessly
npx playwright install --with-deps --only-shell

选择加入新的无头模式​

¥Opt-in to new headless mode

你可以使用 'chromium' 通道选择新的无头模式。如 Chrome 官方文档介绍 所示：

¥You can opt into the new headless mode by using 'chromium' channel. As official Chrome documentation puts it:

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

¥New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.

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

¥See issue #33566 for details.

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

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

谷歌浏览器和微软 Edge​

¥Google Chrome & Microsoft Edge

虽然 Playwright 可以下载并使用最新的 Chromium 版本，但它可以针对计算机上可用的品牌 Google Chrome 和 Microsoft Edge 浏览器进行操作（请注意，Playwright 默认情况下不会安装它们）。特别是，当前的 Playwright 版本将支持这些浏览器的 Stable 和 Beta 通道。

¥While Playwright can download and use the recent Chromium build, it can operate against the branded Google Chrome and Microsoft Edge browsers available on the machine (note that Playwright doesn't install them by default). In particular, the current Playwright version will support Stable and Beta channels of these browsers.

可用通道为 chrome、msedge、chrome-beta、msedge-beta、chrome-dev、msedge-dev、chrome-canary、msedge-canary。

¥Available channels are chrome, msedge, chrome-beta, msedge-beta, chrome-dev, msedge-dev, chrome-canary, msedge-canary.

警告

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

¥Certain Enterprise Browser Policies may impact Playwright's ability to launch and control Google Chrome and Microsoft Edge. Running in an environment with browser policies is outside of the Playwright project's scope.

警告

Google Chrome 和 Microsoft Edge 已切换到更接近常规标题模式的 新的无头模式 实现。这与 Playwright 在无头运行时默认使用的 chromium 无头外壳 不同，因此在某些情况下会出现不同的行为。有关详细信息，请参阅 问题 #33566。

¥Google Chrome and Microsoft Edge have switched to a new headless mode implementation that is closer to a regular headed mode. This differs from chromium headless shell that is used in Playwright by default when running headless, so expect different behavior in some cases. See issue #33566 fore details.

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

export default defineConfig({
  projects: [
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or "msedge-beta" or 'msedge-dev'
    },
  ],
});

安装 Google Chrome 和 Microsoft Edge​

¥Installing Google Chrome & Microsoft Edge

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

¥If Google Chrome or Microsoft Edge is not available on your machine, you can install them using the Playwright command line tool:

npx playwright install msedge
警告

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

¥Google Chrome or Microsoft Edge installations will be installed at the default global location of your operating system overriding your current browser installation.

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

¥Run with the --help option to see a full a list of browsers that can be installed.

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

¥When to use Google Chrome & Microsoft Edge and when not to?

默认值​

¥Defaults

大多数时候，将默认的 Playwright 配置与最新的 Chromium 结合使用是一个好主意。由于 Playwright 领先于浏览器的稳定渠道，因此即将发布的 Google Chrome 或 Microsoft Edge 版本不会破坏你的网站，这让你高枕无忧。你可以尽早发现损坏，并在官方 Chrome 更新之前有很多时间来修复它。

¥Using the default Playwright configuration with the latest Chromium is a good idea most of the time. Since Playwright is ahead of Stable channels for the browsers, it gives peace of mind that the upcoming Google Chrome or Microsoft Edge releases won't break your site. You catch breakage early and have a lot of time to fix it before the official Chrome update.

回归测试​

¥Regression testing

话虽如此，测试策略通常需要针对当前公开可用的浏览器执行回归测试。在这种情况下，你可以选择稳定渠道之一："chrome" 或 "msedge"。

¥Having said that, testing policies often require regression testing to be performed against the current publicly available browsers. In this case, you can opt into one of the stable channels, "chrome" or "msedge".

媒体编解码器​

¥Media codecs

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

¥Another reason for testing using official binaries is to test functionality related to media codecs. Chromium does not have all the codecs that Google Chrome or Microsoft Edge are bundling due to various licensing considerations and agreements. If your site relies on this kind of codecs (which is rarely the case), you will also want to use the official channel.

企业政策​

¥Enterprise policy

Google Chrome 和 Microsoft Edge 尊重企业政策，其中包括对功能、网络代理、妨碍测试的强制扩展的限制。因此，如果你是使用此类策略的组织的一部分，最简单的方法是使用打包的 Chromium 进行本地测试，你仍然可以选择进入通常不受此类限制的机器人上的稳定渠道。

¥Google Chrome and Microsoft Edge respect enterprise policies, which include limitations to the capabilities, network proxy, mandatory extensions that stand in the way of testing. So if you are part of the organization that uses such policies, it is easiest to use bundled Chromium for your local testing, you can still opt into stable channels on the bots that are typically free of such restrictions.

火狐浏览器​

¥Firefox

Playwright 的 Firefox 版本与最近的 火狐稳定版 版本相匹配。Playwright 不适用于品牌版 Firefox，因为它依赖于补丁。

¥Playwright's Firefox version matches the recent Firefox Stable build. Playwright doesn't work with the branded version of Firefox since it relies on patches.

请注意，某些功能的可用性可能因操作系统而异，这些功能在很大程度上取决于底层平台。例如，Linux、macOS 和 Windows 之间可用的媒体编解码器差异很大。

¥Note that availability of certain features, which depend heavily on the underlying platform, may vary between operating systems. For example, available media codecs vary substantially between Linux, macOS and Windows.

WebKit​

Playwright 的 WebKit 源自最新的 WebKit 主分支源，通常在这些更新被纳入 Apple Safari 和其他基于 WebKit 的浏览器之前。这提供了大量的准备时间来对潜在的浏览器更新问题做出反应。Playwright 不适用于 Safari 的品牌版本，因为它依赖于补丁。相反，你可以使用最新的 WebKit 版本进行测试。

¥Playwright's WebKit is derived from the latest WebKit main branch sources, often before these updates are incorporated into Apple Safari and other WebKit-based browsers. This gives a lot of lead time to react on the potential browser update issues. Playwright doesn't work with the branded version of Safari since it relies on patches. Instead, you can test using the most recent WebKit build.

请注意，某些功能的可用性可能因操作系统而异，这些功能在很大程度上取决于底层平台。例如，Linux、macOS 和 Windows 之间可用的媒体编解码器差异很大。虽然在 Linux CI 上运行 WebKit 通常是最实惠的选择，但为了获得最接近 Safari 的体验，你应该在 Mac 上运行 WebKit，例如如果你进行视频播放。

¥Note that availability of certain features, which depend heavily on the underlying platform, may vary between operating systems. For example, available media codecs vary substantially between Linux, macOS and Windows. While running WebKit on Linux CI is usually the most affordable option, for the closest-to-Safari experience you should run WebKit on mac, for example if you do video playback.

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

¥Install behind a firewall or a proxy

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

¥By default, Playwright downloads browsers from Microsoft's CDN.

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

¥Sometimes companies maintain an internal proxy that blocks direct access to the public resources. In this case, Playwright can be configured to download browsers via a proxy server.

HTTPS_PROXY=https://192.0.2.1 npx playwright install

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

¥If the requests of the proxy get intercepted with a custom untrusted certificate authority (CA) and it yields to Error: self signed certificate in certificate chain while downloading the browsers, you must set your custom root certificates via the NODE_EXTRA_CA_CERTS environment variable before installing the browsers:

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

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

¥If your network is slow to connect to Playwright browser archive, you can increase the connection timeout in milliseconds with PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT environment variable:

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

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

¥If you are installing dependencies and need to use a proxy on Linux, make sure to run the command as a root user. Otherwise, Playwright will attempt to become a root and will not pass environment variables like HTTPS_PROXY to the linux package manager.

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

从工件存储库下载​

¥Download from artifact repository

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

¥By default, Playwright downloads browsers from Microsoft's CDN.

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

¥Sometimes companies maintain an internal artifact repository to host browser binaries. In this case, Playwright can be configured to download from a custom location using the PLAYWRIGHT_DOWNLOAD_HOST env variable.

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

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

¥It is also possible to use a per-browser download hosts using PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST, PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST and PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST env variables that take precedence over PLAYWRIGHT_DOWNLOAD_HOST.

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

管理浏览器二进制文件​

¥Managing browser binaries

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

¥Playwright downloads Chromium, WebKit and Firefox browsers into the OS-specific cache folders:

  • Windows 上的 %USERPROFILE%\AppData\Local\ms-playwright

    ¥%USERPROFILE%\AppData\Local\ms-playwright on Windows

  • macOS 上的 ~/Library/Caches/ms-playwright

    ¥~/Library/Caches/ms-playwright on macOS

  • Linux 上的 ~/.cache/ms-playwright

    ¥~/.cache/ms-playwright on Linux

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

¥These browsers will take a few hundred megabytes of disk space when installed:

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

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

¥You can override default behavior using environment variables. When installing Playwright, ask it to download browsers into a specific location:

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

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

¥When running Playwright scripts, ask it to search for browsers in a shared location.

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

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

¥Playwright keeps track of packages that need those browsers and will garbage collect them as you update Playwright to the newer versions.

注意

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

¥Developers can opt-in in this mode via exporting PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers in their .bashrc.

密封安装​

¥Hermetic install

你可以选择密封安装并将二进制文件放置在本地文件夹中：

¥You can opt into the hermetic install and place binaries in the local folder:

# Places binaries to node_modules/playwright-core/.local-browsers
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install
注意

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

¥PLAYWRIGHT_BROWSERS_PATH does not change installation path for Google Chrome and Microsoft Edge.

旧浏览器删除​

¥Stale browser removal

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

¥Playwright keeps track of the clients that use its browsers. When there are no more clients that require a particular version of the browser, that version is deleted from the system. That way you can safely use Playwright instances of different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.

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

¥To opt-out from the unused browser removal, you can set the PLAYWRIGHT_SKIP_BROWSER_GC=1 environment variable.

卸载浏览器​

¥Uninstall browsers

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

¥This will remove the browsers (chromium, firefox, webkit) of the current Playwright installation:

npx playwright uninstall

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

¥To remove browsers of other Playwright installations as well, pass --all flag:

npx playwright uninstall --all