Playwright Java 入门指南：Maven 安装、首个浏览器脚本与底层驱动机制解析

本文基于 Playwright 官方文档 intro-java.md 展开，介绍如何用 Maven 引入 Playwright Java 依赖并跑通第一个浏览器自动化脚本，同时结合仓库源码剖析 Java 客户端如何驱动内置 Node.js 驱动进程、浏览器二进制如何下载与管理。读完后你应能独立完成 Java 项目的 Playwright 接入，并在无头/有头模式下执行脚本、截图、配置代理与浏览器缓存路径。

一、Playwright 是什么

Playwright 是专为端到端（E2E）测试设计的自动化框架，统一 API 支持三大渲染引擎：Chromium、WebKit 和 Firefox。它可在 Windows、Linux、macOS 上运行，支持本地或 CI 环境、无头（headless）或有头（headed）模式，并内置原生移动端模拟能力（见 intro-java.md）。

对 Java 开发者而言，Playwright 以一组 Maven 模块形式分发，最简单的接入方式就是在项目 pom.xml 中添加一个依赖。

二、Maven 项目配置与最小可运行程序

2.1 示例程序 App.java

文档给出的起步示例是启动 Chromium、打开页面并打印标题（完整示例见 intro-java.md）：

package org.example;

import com.microsoft.playwright.*;

public class App {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().launch();
            Page page = browser.newPage();
            page.navigate("https://playwright.dev");
            System.out.println(page.title());
        }
    }
}

注意 try-with-resources 的写法：Playwright 实现 AutoCloseable，离开代码块时自动关闭底层连接与进程，避免浏览器进程泄漏。

2.2 pom.xml 依赖与编译器配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.example</groupId>
  <artifactId>examples</artifactId>
  <version>0.1-SNAPSHOT</version>
  <name>Playwright Client Examples</name>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.microsoft.playwright</groupId>
      <artifactId>playwright</artifactId>
      <version>%%VERSION%%</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.10.1</version>
        <!-- References to interface static methods are allowed only at source level 1.8 or above -->
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

两个要点：

• 文档中的 %%VERSION%% 是文档构建系统的版本占位符，实际使用时请替换为当前 Playwright 发布的版本号；
• maven-compiler-plugin 的 <source>1.8</source>/<target>1.8</target> 不是可选项——注释明确说明“接口静态方法的引用仅在 source level 1.8 及以上才被允许”，这与后文系统要求中“Java 8 或更高”的要求一致。

三、编译运行与首个脚本

3.1 运行命令

mvn compile exec:java -D exec.mainClass="org.example.App"

文档特别指出：首次运行会下载 Playwright 驱动包并自动安装 Chromium、Firefox、WebKit 三个浏览器的二进制文件（见 intro-java.md）。要修改这一行为（例如只装某个浏览器、跳过下载、走代理），参见 browsers.md 中“Install browsers”与“Install behind a firewall or a proxy”章节的说明。

3.2 第一个脚本：WebKit 下截图

文档的“First script”示例改用 WebKit 打开 playwright.dev 并保存截图（见 intro-java.md）：

package org.example;

import com.microsoft.playwright.*;
import java.nio.file.Paths;

public class App {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = playwright.webkit().launch();
      Page page = browser.newPage();
      page.navigate("https://playwright.dev/");
      page.screenshot(new Page.ScreenshotOptions().setPath(Paths.get("example.png")));
    }
  }
}

浏览器类型通过 Playwright 实例上的 chromium() / firefox() / webkit() 工厂方法选择，均返回一个 BrowserType，其 launch() 方法接受一个 BrowserType.LaunchOptions 构建器对象。

3.3 无头模式、有头模式与 slowMo

默认情况下 Playwright 以 headless 模式运行浏览器，不会弹出任何浏览器窗口。要看到浏览器 UI，将 headless 选项设为 false；还可以用 slowMo 选项（单位毫秒）减速执行，便于肉眼观察步骤。这两个选项在 API 文档 class-browsertype.md 中有完整定义（BrowserType.launch.headless、BrowserType.launch.slowMo）：

playwright.firefox().launch(new BrowserType.LaunchOptions().setHeadless(false).setSlowMo(50));

更深入的调试手段（Inspector、断点、Trace 等）可继续阅读 debug.md。

四、系统要求

文档明确列出的官方支持范围（见 intro-java.md）：

• Java 8 或更高版本；
• Windows 11+、Windows Server 2019+ 或 WSL；
• macOS 14（Sonoma）或更高版本；
• Debian 12 / 13、Ubuntu 22.04 / 24.04 / 26.04（x86-64 或 arm64 架构）。

五、源码剖析：Java 客户端如何驱动浏览器

Playwright 各语言客户端本质上是“薄封装 + 内嵌 Node.js 驱动”。从源码结构看，Java/Python/.NET 等客户端库内嵌了一份 Playwright 的 Node.js 驱动（playwright-core），由客户端进程以子进程方式拉起。以仓库中的 outofprocess.ts 为例：

this._driverProcess = childProcess.fork(path.join(packageRoot, 'cli.js'), ['run-driver'], { ... });
...
const transport = new PipeTransport(this._driverProcess.stdin!, this._driverProcess.stdout!);

也就是说：Playwright.create() 之后，客户端会 fork 出 cli.js run-driver 子进程，并通过 stdin/stdout 管道（PipeTransport）与其交换协议消息；close() 时销毁这些管道并终止子进程。这解释了文档中的两个现象：

1. 首次运行 Maven 程序时为什么会“下载 Playwright 包并安装浏览器”——客户端需要完整的驱动与浏览器二进制才能完成握手；
2. 为什么 browsers.md 提供了 PLAYWRIGHT_NODEJS_PATH 环境变量：驱动子进程默认使用 Playwright 内置（bundled）的 Node.js 运行时，在需要锁定 Node 版本或内置运行时不兼容的环境中，可用该变量指向预装的 node 可执行文件。

六、浏览器安装、下载与环境变量（实战配置）

Java 语言下，所有 CLI 命令通过 Maven 执行驱动内的 com.microsoft.playwright.CLI 主类（命令对照见 browsers.md）：

# 安装默认全部浏览器
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"

# 安装系统依赖（适合 CI，Linux 下通常需 root，注意代理变量透传）
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps"

结合 browsers.md 的说明与 server/registry/index.ts 中的实现，常用的环境变量如下：

环境变量	作用	源码依据
PLAYWRIGHT_BROWSERS_PATH	覆盖浏览器二进制的默认缓存目录（Windows %USERPROFILE%\AppData\Local\ms-playwright、macOS ~/Library/Caches/ms-playwright、Linux ~/.cache/ms-playwright）	registry/index.ts
PLAYWRIGHT_DOWNLOAD_HOST	从自建制品库而非默认 CDN 下载浏览器；另有 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST / PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST / PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 按浏览器优先级覆盖	registry/index.ts
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT	下载连接超时（毫秒），网络较慢时可调大	registry/index.ts
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD	设为 1 时跳过浏览器下载，日志会提示“Skipping browsers download because PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD env variable is set”	registry/index.ts
HTTPS_PROXY	内网代理环境下经代理下载浏览器	browsers.md
PLAYWRIGHT_NODEJS_PATH	让驱动使用预装的 Node.js 而非内置运行时	browsers.md

代理场景下还有一个易错点：Linux 上执行 install-deps 时，如果命令以 root 身份重新提权，HTTPS_PROXY 等环境变量不会透传给包管理器，官方建议写成 sudo HTTPS_PROXY=https://proxy npx playwright install-deps 的形式（Java 下同理，将环境变量前缀加在 mvn 命令之前，见 browsers.md）。

另外，纯 headless 场景可用 install --only-shell 只下载 Chromium headless shell 以节省体积；反过来，指定 channel: "chromium"（新版无头模式）后可用 --no-shell 跳过 headless shell，Java 示例见 browsers.md。

七、下一步：从脚本走向测试工程

安装与首跑完成之后，官方文档为 Java 语言规划了如下进阶路径（对应 intro-java.md 的 What's next）：

• 编写测试（writing-tests-java.md）：使用 web-first 断言（assertThat(page).hasTitle(...) 等自动重试断言）、Locator 定位（page.getByRole、text= 等）与 BrowserContext 隔离，为每个测试创建独立的 BrowserContext 和 Page；
• 运行与调试（running-tests-java.md）：推荐接入 JUnit，@BeforeAll 中创建 Playwright/Browser 并 @AfterAll 关闭，@BeforeEach/@AfterEach 中创建/关闭每测试独立的 BrowserContext 与 Page，保证测试隔离；需要可视调试时用 launch(new BrowserType.LaunchOptions().setHeadless(false))；
• 录制生成测试（codegen.md）：用 Codegen 录制操作并生成代码；
• Trace 查看（trace-viewer-intro-java-python.md）：回放测试执行的时间线与截图，定位失败现场。

掌握以上四步后，即可把本文中的 mvn compile exec:java 起步流程平滑升级为并行、隔离、可调试的 Java E2E 测试体系。