浏览器

简介

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

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

安装浏览器

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

pwsh bin/Debug/netX/playwright.ps1 install

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

pwsh bin/Debug/netX/playwright.ps1 install webkit

查看所有支持的浏览器：

pwsh bin/Debug/netX/playwright.ps1 install --help

通过API安装浏览器

可以通过.NET API运行命令行工具命令：

var exitCode = Microsoft.Playwright.Program.Main(new[] {"install"});
if (exitCode != 0)
{
    throw new Exception($"Playwright exited with code {exitCode}");
}

安装系统依赖项

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

pwsh bin/Debug/netX/playwright.ps1 install-deps

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

pwsh bin/Debug/netX/playwright.ps1 install-deps chromium

也可以将install-deps与install结合起来，这样只需一条命令即可安装浏览器和操作系统依赖项。

pwsh bin/Debug/netX/playwright.ps1 install --with-deps chromium

查看系统要求了解官方支持的操作系统。

配置浏览器

Playwright可以在Chromium、WebKit和Firefox浏览器以及品牌浏览器如Google Chrome和Microsoft Edge上运行测试。它还可以在模拟的平板电脑和移动设备上运行。查看设备参数注册表获取完整的选定桌面、平板和移动设备列表。

在不同浏览器上运行测试

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

dotnet test -- Playwright.BrowserName=webkit

要在多个浏览器或配置上运行测试，您需要多次调用dotnet test命令。您可以通过设置BROWSER环境变量或通过runsettings文件配置Playwright.BrowserName来实现：

dotnet test --settings:chromium.runsettings
dotnet test --settings:firefox.runsettings
dotnet test --settings:webkit.runsettings

<?xml version="1.0" encoding="utf-8"?>
  <RunSettings>
    <Playwright>
      <BrowserName>chromium</BrowserName>
    </Playwright>
  </RunSettings>

Chromium

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

Chromium: 无头浏览器外壳

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

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

# only running tests headlessly
pwsh bin/Debug/netX/playwright.ps1 install --with-deps --only-shell

Chromium: 新的无头模式

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

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

详情请参见issue #33566。

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <Playwright>
    <BrowserName>chromium</BrowserName>
    <LaunchOptions>
      <Channel>chromium</Channel>
    </LaunchOptions>
  </Playwright>
</RunSettings>

dotnet test -- Playwright.BrowserName=chromium Playwright.LaunchOptions.Channel=chromium

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

# only running tests headlessly
pwsh bin/Debug/netX/playwright.ps1 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。

warning

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

warning

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

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <Playwright>
    <BrowserName>chromium</BrowserName>
    <LaunchOptions>
      <Channel>msedge</Channel>
    </LaunchOptions>
  </Playwright>
</RunSettings>

dotnet test -- Playwright.BrowserName=chromium Playwright.LaunchOptions.Channel=msedge

安装Google Chrome和Microsoft Edge

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

pwsh bin/Debug/netX/playwright.ps1 install msedge

warning

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

HTTPS_PROXY=https://192.0.2.1 pwsh bin/Debug/netX/playwright.ps1 install

$Env:HTTPS_PROXY="https://192.0.2.1"
pwsh bin/Debug/netX/playwright.ps1 install

set HTTPS_PROXY=https://192.0.2.1
pwsh bin/Debug/netX/playwright.ps1 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 pwsh bin/Debug/netX/playwright.ps1 install

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
pwsh bin/Debug/netX/playwright.ps1 install

set PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
pwsh bin/Debug/netX/playwright.ps1 install

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

sudo HTTPS_PROXY=https://192.0.2.1 pwsh bin/Debug/netX/playwright.ps1 install-deps

从制品仓库下载

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

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

Bash
PowerShell
批量处理

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 pwsh bin/Debug/netX/playwright.ps1 install

$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
pwsh bin/Debug/netX/playwright.ps1 install

set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
pwsh bin/Debug/netX/playwright.ps1 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 pwsh bin/Debug/netX/playwright.ps1 install

$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
$Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="http://203.0.113.3"
pwsh bin/Debug/netX/playwright.ps1 install

set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3
set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
pwsh bin/Debug/netX/playwright.ps1 install

管理浏览器二进制文件

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

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

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers pwsh bin/Debug/netX/playwright.ps1 install

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
pwsh bin/Debug/netX/playwright.ps1 install

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
pwsh bin/Debug/netX/playwright.ps1 install

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

Bash
PowerShell
批量处理

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers dotnet test

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

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

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

note

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

过时浏览器清理

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

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

卸载浏览器

这将移除当前Playwright安装中的浏览器(chromium, firefox, webkit):

pwsh bin/Debug/netX/playwright.ps1 uninstall

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

pwsh bin/Debug/netX/playwright.ps1 uninstall --all

简介​

安装浏览器​

通过API安装浏览器​

安装系统依赖项​

配置浏览器​

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

Chromium​

Chromium: 无头浏览器外壳​

Chromium: 新的无头模式​

Google Chrome 和 Microsoft Edge​

安装Google Chrome和Microsoft Edge​

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

默认值​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理服务器后安装​

从制品仓库下载​

管理浏览器二进制文件​

过时浏览器清理​

卸载浏览器​

简介

安装浏览器

通过API安装浏览器

安装系统依赖项

配置浏览器

在不同浏览器上运行测试

Chromium

Chromium: 无头浏览器外壳

Chromium: 新的无头模式

Google Chrome 和 Microsoft Edge

安装Google Chrome和Microsoft Edge

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

默认值

回归测试

媒体编解码器

企业策略

Firefox

WebKit

在防火墙或代理服务器后安装

从制品仓库下载

管理浏览器二进制文件

过时浏览器清理

卸载浏览器