源码教程：Chrome 走 CDP 与 CDP 客户端

本机 Google Chrome 一律通过 CDP（Chrome DevTools Protocol） 驱动：服务自己拉进程、开远程调试端口、用协议接上。为此工程里多了一个独立的协议客户端，包名 nexus.io.chromium.cdp，它不依赖工程内其它包，可以整包拿走单独用。

前文 05 讲的是「用哪个浏览器、用哪份 profile」的表现，本文讲这条启动路径本身怎么实现、为什么这么实现、以及踩过哪些坑。

一、为什么本机 Chrome 走 CDP

内置 Chromium 仍走 Playwright 的持久化上下文：它不需要「本机安装」这个概念，开发态还没有内嵌可执行文件（交给 Playwright 自己解析），换成自己拉进程只会多一份要维护的启动逻辑。Edge 走 CDP 更早，原因在沙箱（见 05 第六节）。

二、启动链路

PlaywrightService.launchChromiumFamily
  → 解析出固定的 cdp 托管 profile 目录（ChromeBrowser.cdpManagedProfileDir）
  → PlaywrightService.cdpArgs：拼启动参数，含 --remote-debugging-port=<配置端口或 0>
  → ChromeLauncher.launch：ProcessBuilder 拉进程，边读 stderr 边等调试地址
       DevTools listening on ws://127.0.0.1:<port>/...
  → 把 ws 地址换成 HTTP 端点（http://127.0.0.1:<端口>）
  → Playwright 的 connectOverCDP 接上（全量命令仍走这条已有的执行链）
  → CdpLaunchSupport.apply：用独立 CDP 客户端再连一次，补创建期参数并回报浏览器身份

两条连接并存不是重复：前者负责全部 121 个命令，后者负责「持久化上下文原本在创建时给好、而 CDP 没有对应入口」的那几项，并且把浏览器亲口报的版本写进回执，让 mode:cdp 这句自述有第三方证据。

ChromeLauncher 有几处刻意的实现选择：

• 从 stderr 读调试地址，而不是读 DevToolsActivePort 文件：那个文件只在非默认用户数据目录下才会被写出来。托管 profile 恰好是非默认目录，但用户 profile 不是，两条路统一走 stderr，少一个分支。
• 区分「拒绝」与「提前退出」：Chrome 明确拒绝远程调试时会打印 DevTools remote debugging requires a non-default data directory，此时它不会自己退出（会变成一个普通浏览器继续跑），所以服务必须自己把它收掉；而 profile 被占用时新进程会立刻退出（见第八节）。
• 不读输出会把浏览器堵死：读线程必须一直把 stdout/stderr 读干净。

三、独立客户端 nexus.io.chromium.cdp

为什么自己写而不是引一个协议库。 现成的选择分两类，都不合适：一类是多年没有发版的社区客户端；另一类是按浏览器里程碑逐个发版的协议绑定 —— 用它等于把「升级浏览器」和「升级依赖」绑在一起，而这个工程本来就自己内嵌浏览器、自己控制版本。这个客户端只需要「连上任意版本的 Chromium 系浏览器、收发协议消息」，自己实现反而更小：只用 JDK 自带的 WebSocket 客户端加上工程已有的 JSON 工具，没有新增依赖。

这个包不 import 工程内任何其它包，所以它可以被整包复制到别的项目里。它的自测也刻意不借用工程的启动工具：src/test/java/nexus/io/chromium/cdp/CdpClientTest.java 自己探测浏览器可执行文件、自己挑空闲端口、自己拉进程、自己等端口就绪，覆盖连接、导航、求值、异步求值、截图、会话隔离、target 列表、失败分型与连接状态自述。

四、三个关键机制

4.1 命令与回执靠自增 id 配对

每条命令分配一个自增 id 放进消息，回执按 id 唤醒等待方。调用方可以从任意线程发命令；事件回调则在读 WebSocket 的那条线程上执行，所以回调里不要做阻塞的协议同步调用（那会把后续所有事件堵在后面）。

4.2 事件按 sessionId 路由

浏览器级命令不带 sessionId，页签 / 子 frame 级的命令与事件带。扁平模式（挂载 target 时带 flatten）下不再需要把消息层层套进 sendMessageToTarget，所有命令与事件都走同一条 WebSocket，靠 sessionId 区分。

为什么必须按 target 分会话：跨域 iframe 在 Chromium 里是独立渲染进程，它是自己的 target、有自己的执行上下文。在顶层会话里求值，document 永远是顶层文档的；要进 iframe 内部求值，只能用属于那个 frame 的会话，或在该会话里指定执行上下文。

4.3 失败要分得清

第三类是最容易被写错的一类：超时只说明「没等到回执」，动作可能已经落到页面上。把它统一当失败然后自动重发，就是重复提交的来源。

五、创建期参数怎么补

CdpLaunchSupport 在接上浏览器之后补两件事，并把结果写进 start 回执的 data.browser.cdp.notes：

权限名不是 Playwright 那一套。 Playwright 的 setPermissions 收 clipboard-read / clipboard-write，而协议的 PermissionType 里叫 clipboardReadWrite / clipboardSanitizedWrite。照抄 Playwright 的名字会得到 Unknown permission type —— 而这类错误一旦被兜住，表现就是剪贴板按钮静默失效，在站点侧完全看不出是权限问题。自测里专门留了一条反向用例把这个坑钉住。

两条都是尽力而为：失败只记警告并写进 notes，绝不让 start 失败。用「少一个下载目录设置」换「整个任务起不来」是明显的亏本买卖；但也不能不吭声，所以失败原因必须出现在回执里。

另外一个协议特性值得单独提：打开自动挂载并让新 target 停在调试器前时，必须有人放行（Runtime.runIfWaitingForDebugger），否则新页签永远白屏。这个客户端在打开开关的同时就注册了「收到挂载事件立刻放行」的监听器，不把「忘了放行」留给调用方。

六、回执里多了什么

{"data":{"browser":{"type":"chrome","engine":"chromium","mode":"cdp","userProfile":false,
  "profileDir":"<托管 profile 绝对路径>","headless":false,
  "cdp":{"product":"Chrome/<版本>","protocolVersion":"<协议版本>",
    "notes":["下载目录:<路径>(Browser.setDownloadBehavior)","已授权限:clipboardReadWrite / clipboardSanitizedWrite / notifications"]}}}}

mode 是服务自己的说法，cdp.product 是浏览器亲口报的（Browser.getVersion 的 product）。排查版本相关问题时先看它。notes 记录补设置的实际结果，成功与失败都在里面。

七、profile：固定一份，不按端口派生

本机 Chrome 走 CDP 时用的托管 profile 默认是 ~/.config/browseruse/profiles/shared-default，由 browser.chrome.cdpProfileDir 控制。

为什么不按端口派生。 按端口派生（shared-<端口>）是为了让多个服务实例各自一份 profile、不抢锁。但这条路用的是托管 profile，本来就不会和用户正在开的 Chrome 抢目录；再按端口分只会带来一个纯粹损失：换端口等于换一套登录态。固定成 shared-default 之后，换端口不换登录态。

解析优先级：browser.chrome.cdpProfileDir > browser.profileDir（显式配置永远优先，想跟旧的托管目录共用一份登录态就指过去）> shared-default。想用用户自己那份 Chrome profile（现成的 Google 登录态）请打开 browser.chrome.useUserProfile，那用的是系统默认的 User Data，与这一份无关 —— 详见 05 第四节。

从「按端口派生的托管 profile」切到 shared-default 时，登录态不会跟着走：那是两个不同的目录。要沿用旧目录，用 browser.chrome.cdpProfileDir 或 browser.profileDir 显式指过去。

八、排障

8.1 启动后立即退出、而且「没有输出」

现象：start 失败，报「浏览器启动后立即退出（退出码 21）：(Chrome 没有输出)」。

原因几乎只有一个：这份托管 profile 已经被另一个 Chrome 占着。新进程把命令行交给已有实例后自己退出，而输出也被那个实例吃掉了，所以只看启动器的报错会得到一句「没有输出」，完全指不到方向。

正常只可能有两个来源：上一次服务被强杀留下的孤儿浏览器，或者人手工起的调试实例。查法：看哪个 chrome 进程的命令行里带着这个 profile 目录。

Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" |
  Where-Object { $_.CommandLine -like '*shared-default*' } |
  Select-Object ProcessId, CommandLine

8.2 调试端口：为什么不写 9222

9222 不是浏览器的内置默认值：Chromium 系浏览器要求显式传 --remote-debugging-port。9222 只是 Puppeteer / Selenium / 各类编辑器插件约定俗成用的端口。

跟着用它的代价是双向的：任何同样按默认值连 9222 的工具都会连到我们的浏览器上；反过来，别人手工起的调试实例会占着端口与 profile，让我们的启动失败 —— 8.1 那个「退出码 21、没有输出」就是这么来的。

所以默认值是 0：让浏览器自己挑一个空闲端口，端口号从它的 stderr 里读出来。这样不会有端口被占用的启动失败，同一台机器跑多个实例也不会互相踩，挑出来的端口一定在 10000 以上。需要稳定端点（想用别的工具接上来看、或要固定防火墙规则）时，用 browser.chrome.debugPort 钉一个 10000 以上的端口。

8.3 set_credentials 在这条路上用不了

HTTP 基本认证的凭据只能在创建上下文时设置，而这条路的上下文不是由 Playwright 创建的，也没法重建。需要它时改用 browser=chromium（内置 Chromium，走持久化上下文）或 browser=firefox。失败信息里会直接给出这两个取值。

九、自测怎么证明它真的能用

协议库这种「薄」组件最容易出现「编译过了、其实没连上」的情况，所以自测是一条不依赖工程其它代码的端到端用例：

• 自己探测浏览器可执行文件；找不到就整类跳过（这台机器上没装浏览器不算失败）。
• 自己挑空闲端口、用临时 profile 目录拉一个无头浏览器，不碰开发机上那份登录态。
• 断言覆盖：浏览器版本前缀、协议版本、导航与标题、document 求值、异步表达式（Promise）求值、截图字节是合法 PNG、两个页签的会话不串台、target 列表能解析、页面内异常与协议级拒绝分型正确、连接对象能自述存活状态。
• 反向用例：Playwright 的权限名确实会被协议拒绝，把这个容易犯、后果又静默的错误钉住。

配置与运维视角的清单见 12，浏览器与 profile 的表现见 05。