Playwright 通过 CDP 连接已有 Chromium：状态保留与重启验证

Playwright 已经连接成功，页面也能正常创建，但账号变成了未登录状态；浏览器原本配置了代理，脚本访问页面时却走了另一条出口；任务中断后重新连接，Profile ID 没变，本地状态却没有按预期恢复。

这些现象说明，代码连接到浏览器，只能证明控制通道已经建立。它不能单独证明当前连接的是目标环境，也不能证明登录状态、存储数据和网络路径仍然正确。

这种接入方式常见于远程浏览器、环境管理工具，以及其他预先启动并开放调试端口的 Chromium 环境。

CDP 接入需要验证三层结果

第一层是建立连接。

脚本成功取得 Browser、BrowserContext 或 Page 对象，说明 Playwright 已经找到浏览器，并且能够发送控制指令。

第二层是连接到指定环境。

传给 connectOverCDP() 的地址应来自目标 Profile 的本次启动结果，不能混用旧端口、其他环境返回的连接地址，或仅凭浏览器窗口名称判断当前环境。

通过 browser.contexts()[0] 获取 CDP 连接后的 default context 是正常用法。真正需要记录的是当前 endpoint 对应的 Profile ID、启动时间和任务编号。

第三层是当前任务依赖的状态仍然正确。

不同任务需要检查的内容并不相同：

• 依赖账号登录时，检查 Cookie 和站点存储；
• 依赖固定网络出口时，检查浏览器页面内的实际 IP；
• 需要周期性恢复时，检查 Profile 重启后的状态；
• 需要人工介入时，确认操作者能够回到同一环境；
• 由多人维护时，确认环境归属和权限记录。

建立连接、连接到目标环境，并通过当前任务依赖的关键状态检查后，这个 CDP 接入才算真正可用。

接入已有浏览器前，先判断状态需要保存到什么程度

Playwright 本身既能创建临时隔离会话，也能使用持久用户数据目录，还能连接已经启动的 Chromium。三种方式解决的状态范围不同。

普通 BrowserContext 的重点是隔离。不同 Context 之间不会共享 Cookie 和缓存，但非持久化 Context 关闭后不会继续保存完整会话目录。

launchPersistentContext() 会使用指定的 User Data Directory。只要任务目标是让 Cookie、LocalStorage 等状态跨运行保留，Playwright 自己就可以维护持久目录。

不过，同一个 userDataDir 不能同时被多个浏览器实例占用，也不应直接指向日常 Chrome 使用的主用户目录。自动化任务应准备独立目录，避免与正在运行的浏览器争用数据。

当任务还需要把代理、登录状态、浏览器配置和环境标识长期对应起来，或者需要在脚本控制与人工操作之间切换时，通常会改为连接外部管理的 Profile。

connectOverCDP() 从 Playwright v1.9 开始提供，只支持 Chromium 系浏览器。Playwright 官方也说明，CDP 连接的能力完整度低于原生 Playwright 协议连接，因此浏览器内核和目标操作仍需分别验证。

代码示例需要对应 Playwright 版本

下面的 TypeScript 示例适用于 Playwright v1.60 及以上版本。

connectOverCDP() 早于 v1.60 已经存在，但示例中的 noDefaults 选项从 v1.60 才开始支持。旧版本需要升级 Playwright，或者删除该选项。

先查看当前版本：

npx playwright --version

再连接目标浏览器启动后返回的 CDP 地址：

import { chromium, type Page } from "playwright";

async function main(): Promise<void> {
  const endpoint = process.env.CDP_ENDPOINT;

  if (!endpoint) {
    throw new Error("缺少 CDP_ENDPOINT");
  }

  const browser = await chromium.connectOverCDP(endpoint, {
    noDefaults: true,
    timeout: 30_000,
  });

  let page: Page | undefined;

  try {
    const [context] = browser.contexts();

    if (!context) {
      throw new Error("连接已经建立，但没有发现 BrowserContext");
    }

    const existingPageCount = context.pages().length;
    page = await context.newPage();

    console.log({
      contextCount: browser.contexts().length,
      existingPageCount,
      pageCountAfterNewPage: context.pages().length,
      newPageInitialUrl: page.url(),
    });
  } finally {
    await page?.close().catch(() => {});
    await browser.close().catch(() => {});
  }
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

这段代码不依赖顶层 await，减少了对 TypeScript 模块配置的要求。执行失败时会输出错误，并将进程退出状态设为非零。

示例没有直接使用 context.pages()[0]。目标环境中可能已经打开多个标签页，第一个页面未必是当前任务需要操作的页面。需要继续使用已有页面时，应根据 URL、页面标题或任务记录进行匹配，而不是依赖标签页顺序。

代码通过 context.newPage() 创建新页面，其初始地址通常是 about:blank。这只能证明页面创建成功，不能证明目标站点可访问、账号状态有效或代理出口正确。

新建页面本身也会改变当前 Profile 的标签页状态，因此示例在 finally 中关闭脚本创建的页面，并通过 browser.close() 结束当前 Playwright 连接。

noDefaults: true 会避免 Playwright 向现有 default context 应用部分默认覆盖，例如下载行为、焦点模拟和媒体模拟设置。

它不能证明当前 Profile、存储状态、代理出口和重启恢复符合预期。这些结果仍需单独检查。

storageState 与完整浏览器环境的区别

不同任务需要保留的状态范围并不相同。

只需要复用登录认证时，Cookie、LocalStorage，以及部分保存在 IndexedDB 中的认证数据，通常可以由 Playwright 的 storageState 保存，再加载到新的 BrowserContext。

如果任务还依赖扩展数据、浏览器设置、历史记录、缓存、代理配置或其他用户目录内容，就需要持久用户数据目录或已有 Profile，并检查关闭、重启后的环境是否一致。

公开页面采集、临时测试或一次性页面操作，则可以使用非持久化 Context 或关闭后删除的一次性环境。此类任务保留全部 Cookie、缓存和历史记录未必有价值，反而会增加清理成本。

Playwright 可以通过 storageState 保存认证状态，并在新的 Context 中复用。它适合测试账号、可重复登录流程，以及由代码统一维护认证文件的任务。

storageState 默认保存 Cookie 和 LocalStorage。Playwright v1.51 及以上版本还可以设置 indexedDB: true，将 IndexedDB 中的认证数据写入状态文件。

保存前可以先创建目录：

import { mkdir } from "node:fs/promises";

const authFile = "playwright/.auth/state.json";

await mkdir("playwright/.auth", {
  recursive: true,
});

await context.storageState({
  path: authFile,
  indexedDB: true,
});

状态文件可能包含能够用于访问测试账号的 Cookie 和认证信息，应将目录加入 .gitignore：

playwright/.auth

创建新的 BrowserContext 时，可以加载保存的状态：

const context = await browser.newContext({
  storageState: "playwright/.auth/state.json",
});

使用 Playwright Test 时，也可以写入配置：

import { defineConfig } from "@playwright/test";

export default defineConfig({
  use: {
    storageState: "playwright/.auth/state.json",
  },
});

这种方式会创建新的 BrowserContext，不是把状态写回通过 CDP 连接的 default context。连接已有 Profile 时，环境状态仍由该 Profile 自己保存和恢复，Playwright 主要负责连接与操作。

SessionStorage 不会由 storageState 自动保存。目标网站依赖 SessionStorage 时，需要自行导出，并通过初始化脚本写入新的 Context。

可以按任务需要区分：

• **只复用认证状态：**使用 storageState；
• **保留完整用户目录：**使用 Persistent Context；
• **每次使用干净环境：**使用临时 BrowserContext 或一次性环境；
• **控制已经启动的浏览器：**通过 CDP 连接目标 Profile。

CDP 是连接方式，不是状态保存方式。状态是否能够恢复，取决于被连接环境的存储实现。

本地浏览器和远程 Chromium 的运行差异

本地环境的浏览器进程和数据位于团队控制的设备上，更适合需要本地文件、浏览器扩展、固定运行设备或直接人工操作的任务。

代价是团队需要自行维护客户端、磁盘空间、浏览器内核和并发资源。

远程 Chromium 将浏览器进程放在服务端，代码通过远程 CDP 地址连接。它更适合不希望维护本地运行机器，或者需要从不同位置访问浏览器会话的流程。

使用远程环境时，需要确认：

• 远程会话是否绑定目标 Profile；
• 断开连接后会话是否继续存在；
• 重新连接时是否恢复同一状态；
• 下载文件保存在什么位置；
• 页面异常时能否观察当前会话；
• 是否允许直接人工交互；
• 人工处理后 Playwright 能否继续控制原会话；
• 并发和运行时长受到哪些限制。

本地与远程的主要差别，是浏览器运行在哪里、由谁维护资源，以及会话中断后怎样观察和恢复。

实时观察和人工操作不是同一种能力

自动化过程中可能出现登录确认、页面结构变化、弹窗、扩展异常或临时授权。

实时观察只能让操作者看到当前页面。人工操作还需要能够点击、输入并处理页面状态。人工处理完成后，原来的 Playwright 连接是否还能继续控制同一会话，则是第三个独立问题。

需要人工介入时，应分别确认：

• 操作者看到的是不是目标 Profile；
• 当前账号和页面状态是否保持不变；
• 只能观看，还是可以实际操作；
• 人工操作是否会改变网络出口或环境配置；
• 处理完成后 Playwright 能否重新连接或继续运行。

重新打开一个相似的浏览器窗口，并不代表已经回到脚本刚才控制的环境。

用同一个小任务验证环境状态

在编写完整业务脚本前，可以先用一个小任务验证当前接入方式。

CDP 接入后的登录状态、网络出口与重启恢复验证流程。

1. 准备测试环境

使用测试账号，不使用生产账号。

在目标环境中：

• 配置一条测试代理；
• 完成一次登录；
• 写入一个可识别的 LocalStorage 值；
• 记录 Profile ID；
• 记录浏览器页面内看到的出口 IP。

2. 启动目标环境

通过对应的启动接口打开目标 Profile，并记录：

• Profile ID；
• CDP 地址；
• 当前运行位置；
• 是否使用持久 Profile；
• 是否显示浏览器窗口。

随后再由 Playwright 连接。

3. 核对脚本看到的状态

连接后检查：

• 当前账号是否仍然登录；
• 测试 LocalStorage 是否存在；
• 页面内的出口 IP 是否符合预期；
• 目标页面操作是否能够完成；
• 下载、弹窗或扩展等必要功能是否可用。

代码能执行，只能证明连接已经建立。以上结果才能说明当前连接满足目标任务。

4. 关闭、重启并按需人工打开

关闭目标环境后，再启动同一个 Profile 并重新连接。

任务需要人工介入时，再由操作者打开同一环境，确认账号状态、页面状态和网络出口与脚本运行时一致。

建立 CDP 连接只是第一步。目标环境、存储状态、网络出口和重启恢复都符合当前任务要求后，这个接入才算真正可用。