瀏覽器

簡介

每個 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：無頭外殼

Playwright 針對有頭操作運送常規 Chromium 建置版本，以及針對無頭模式運送單獨的 chromium 無頭外殼。

如果您僅在無頭外殼中執行測試（即未指定 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 應用程式測試或瀏覽器擴充功能測試。

請參閱 issue #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 選項，在瀏覽器安裝期間跳過下載無頭外殼

# 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 版本將支援這些瀏覽器的穩定版和 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 無頭外殼不同，因此在某些情況下預期會有不同的行為。請參閱 issue #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 尊重企業原則，其中包括對功能、網路 Proxy、強制擴充功能的限制，這些限制阻礙了測試。因此，如果您是使用此類原則的組織的一部分，則最簡單的方法是使用捆綁的 Chromium 進行本機測試，您仍然可以選擇加入通常不受此類限制的 Bot 上的穩定版通道。

Firefox

Playwright 的 Firefox 版本與最新的 Firefox 穩定版建置版本相符。Playwright 無法與品牌版本的 Firefox 搭配使用，因為它依賴修補程式。

請注意，某些功能在不同作業系統之間的可用性可能會有所不同，這些功能在很大程度上取決於底層平台。例如，可用的媒體編解碼器在 Linux、macOS 和 Windows 之間差異很大。

WebKit

Playwright 的 WebKit 源自最新的 WebKit 主要分支來源，通常在這些更新納入 Apple Safari 和其他基於 WebKit 的瀏覽器之前。這為應對潛在的瀏覽器更新問題提供了充足的提前期。Playwright 無法與品牌版本的 Safari 搭配使用，因為它依賴修補程式。相反地，您可以使用最新的 WebKit 建置版本進行測試。

請注意，某些功能在不同作業系統之間的可用性可能會有所不同，這些功能在很大程度上取決於底層平台。例如，可用的媒體編解碼器在 Linux、macOS 和 Windows 之間差異很大。雖然在 Linux CI 上執行 WebKit 通常是最經濟實惠的選項，但為了獲得最接近 Safari 的體驗，您應該在 Mac 上執行 WebKit，例如，如果您進行影片播放。

在防火牆或 Proxy 後方安裝

預設情況下，Playwright 從 Microsoft 的 CDN 下載瀏覽器。

有時公司會維護內部 Proxy，以封鎖對公用資源的直接存取。在這種情況下，可以將 Playwright 設定為透過 Proxy 伺服器下載瀏覽器。

Bash
PowerShell
Batch

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"

如果 Proxy 的請求被自訂不受信任的憑證授權單位 (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

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 上使用 Proxy，請確保以 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
Batch

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
Batch

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"

管理瀏覽器二進位檔

Playwright 將 Chromium、WebKit 和 Firefox 瀏覽器下載到作業系統特定的快取資料夾中

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

這些瀏覽器在安裝後將佔用數百 MB 的磁碟空間

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

您可以使用環境變數覆寫預設行為。安裝 Playwright 時，要求它將瀏覽器下載到特定位置

Bash
PowerShell
Batch

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
Batch

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
Batch

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 安裝的瀏覽器（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：無頭外殼​

Chromium：新的無頭模式​

Google Chrome & Microsoft Edge​

安裝 Google Chrome & Microsoft Edge​

何時使用 Google Chrome & Microsoft Edge，何時不使用？​

預設值​

迴歸測試​

媒體編解碼器​

企業原則​

Firefox​

WebKit​

在防火牆或 Proxy 後方安裝​

從成品儲存庫下載​

管理瀏覽器二進位檔​

略過瀏覽器下載​

移除過時的瀏覽器​

解除安裝瀏覽器​

簡介