Playwright Java 连接已打开浏览器（完整指南）

本文详细讲解如何使用 Playwright for Java 连接并驱动已打开的浏览器实例（Chrome/Edge/Firefox），包含前置操作、核心代码、常见问题及注意事项，内容无冗余且可直接落地。

一、核心原理

要驱动已打开的浏览器，需利用浏览器的 Chrome DevTools Protocol (CDP) 调试协议：

1. 先手动/命令行启动浏览器并开启远程调试端口（直接双击打开的浏览器无调试端口，无法被连接）；
2. Playwright 通过 connectOverCDP() 方法连接该调试端口，实现对已有浏览器实例的控制。

二、前置步骤：启动带调试端口的浏览器

1. Chrome/Edge 启动命令（Windows/macOS/Linux）

Windows 示例

• Chrome：

  "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\temp\chrome-profile"
  

• Edge：

  "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="C:\temp\edge-profile"
  

macOS 示例

• Chrome：

  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-profile"
  

Linux 示例

• Chrome：

  google-chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-profile"
  

2. 参数说明

执行命令后，浏览器会自动打开，此时该实例可被 Playwright 连接。

三、Playwright Java 核心实现

1. 依赖配置（Maven）

在 pom.xml 中引入 Playwright 依赖（建议使用最新版本）：

<dependencies>
    <dependency>
        <groupId>com.microsoft.playwright</groupId>
        <artifactId>playwright</artifactId>
        <version>1.42.1</version>
    </dependency>
</dependencies>

<!-- 可选：自动下载 Playwright 浏览器驱动 -->
<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.playwright</groupId>
            <artifactId>playwright-maven-plugin</artifactId>
            <version>1.42.1</version>
            <executions>
                <execution>
                    <goals>
                        <goal>install</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. 完整代码（连接已打开的浏览器）

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;

/**
 * Playwright Java 连接已打开的浏览器实例
 */
public class ConnectToExistingBrowser {
    public static void main(String[] args) {
        // 调试端口（需和启动浏览器时的端口一致）
        final int DEBUG_PORT = 9222;
        final String CDP_ADDRESS = String.format("http://localhost:%d", DEBUG_PORT);

        // 1. 初始化 Playwright
        try (Playwright playwright = Playwright.create()) {
            // 2. 核心：连接已打开的浏览器（通过 CDP 协议）
            Browser browser = playwright.chromium().connectOverCDP(CDP_ADDRESS);
            System.out.println("✅ 成功连接到已打开的浏览器");

            // 3. 获取浏览器中的页面（按需选择）
            // 方式1：获取第一个上下文的第一个页面（推荐，对应已打开的标签页）
            Page page = browser.contexts().get(0).pages().get(0);
            // 方式2：新建页面（在已有浏览器中打开新标签页）
            // Page page = browser.newContext().newPage();

            // 4. 操作页面（示例）
            System.out.println("📄 当前页面标题：" + page.title());
            page.navigate("https://www.baidu.com"); // 跳转到百度
            System.out.println("📄 跳转后页面标题：" + page.title());
            page.click("#kw"); // 点击百度搜索框
            page.type("#kw", "Playwright Java 连接已打开浏览器"); // 输入内容
            page.click("#su"); // 点击搜索按钮

            // 5. 可选：关闭连接（不关闭则浏览器保持打开，仅断开 Playwright 连接）
            // browser.close();

        } catch (Exception e) {
            System.err.println("❌ 连接失败：" + e.getMessage());
            System.err.println("\n排查方向：");
            System.err.println("1. 浏览器是否通过 --remote-debugging-port=" + DEBUG_PORT + " 启动");
            System.err.println("2. 端口 " + DEBUG_PORT + " 是否被占用（可更换端口重试）");
            System.err.println("3. 浏览器是否保持打开状态");
            e.printStackTrace();
        }
    }
}

3. 代码关键说明

• playwright.chromium()：Chrome/Edge 属于 Chromium 内核，需用该方法；Firefox 需替换为 playwright.firefox()；
• connectOverCDP(CDP_ADDRESS)：核心方法，通过 CDP 地址连接已打开的浏览器；
• browser.contexts().get(0).pages().get(0)：获取浏览器第一个上下文的第一个页面（上下文对应独立会话，页面对应标签页）；
• 异常捕获：增加了连接失败的排查提示，方便新手定位问题。

四、扩展场景：启动新浏览器并开启调试端口

若需通过 Playwright 启动带调试端口的新浏览器（而非连接已打开的），可使用 LaunchOptions 配置参数，代码示例：

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserType;
import com.microsoft.playwright.Playwright;

public class LaunchBrowserWithDebugPort {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            // 配置启动参数（开启调试端口）
            BrowserType.LaunchOptions options = new BrowserType.LaunchOptions()
                    .setHeadless(false) // 显示浏览器窗口
                    .setArgs(new String[]{
                            "--remote-debugging-port=9222",
                            "--user-data-dir=C:\\temp\\chrome-profile"
                    });

            // 启动带调试端口的 Chrome
            Browser browser = playwright.chromium().launch(options);
            System.out.println("✅ 启动带调试端口的浏览器，可通过 9222 端口连接");

            // 后续可正常操作页面
            // Page page = browser.newPage();
        }
    }
}

五、常见问题排查

总结

1. 连接已打开的浏览器核心：启动浏览器时开启调试端口 + 代码中通过 connectOverCDP() 连接该端口；
2. LaunchOptions 仅用于启动新浏览器，连接已有浏览器时无需配置；
3. 调试端口需唯一且未被占用，--user-data-dir 必须设置以避免浏览器实例冲突。