03 CDP 端口探测与架构自校正

03 CDP 端口探测与架构自校正

本节摘要:桌面形态要在多种芯片架构(尤其苹果硅的 Rosetta 情况)上稳定运行,还涉及调试端口(CDP)的分配。本节讲两个跨平台兼容机制:CDP 端口探测(给调试器分一个固定/可用端口)和架构自校正(检测架构不匹配,给对的下载链接)。这些是「让桌面在异构环境稳定跑」的工程细节。

一、CDP:Chrome DevTools Protocol

先说 CDP 是什么。CDP(Chrome DevTools Protocol)是 Chromium 系(Electron 基于 Chromium)的调试协议——通过它,调试器(如 Chrome DevTools、自动化工具)可以连上 Electron 实例,做调试、自动化、截图等。

OpenWork 桌面端用 CDP 做什么?几个场景:

• 开发调试:开发时连 DevTools 调试前端/主进程。
• 自动化测试:评估框架(fraimz,第 13 章)通过 CDP 驱动真实 UI。
• 远程调试:某些场景需要远程连上桌面实例调试。

要用 CDP,Electron 实例得开一个调试端口,调试器连这个端口。

二、CDP 端口探测

CDP 端口不能随便选——它得:

• 可用(不被占)
• 尽量稳定(便于调试器记忆)
• 锁定本机(127.0.0.1,不暴露到网络)

OpenWork 的 CDP 端口探测逻辑大致是:

1. 看环境变量是否指定(如 OPENWORK_ELECTRON_REMOTE_DEBUG_PORT)
   │
   ├─ 指定 ──► 用指定的
   │
   └─ 未指定 ──► 在候选端口列表里探测
        │
        ▼ 候选列表(如 [9223, 9224, 9225, ...])
        │
        ▼ 顺序探测哪个可用
        │
        ▼ 用第一个可用的
   │
   ▼ 锁定 127.0.0.1(不暴露网络)
   │
   ▼ 写到环境变量(供 agent 等引用)
​

候选端口列表是有序的,探测时从前往后找第一个可用的。锁定 127.0.0.1 是安全——CDP 暴露到网络很危险(任何人能调试你的应用),所以只本机。

⚠️ CDP 必须锁本机:CDP 暴露到网络 = 任何人能控制你的 Electron 实例(读内容、执行 JS)。所以 OpenWork 锁 127.0.0.1,这是安全底线。

三、架构自校正:一个容易被忽视的坑

这是本节最实用的部分。考虑这个场景:用户在苹果硅(M1/M2)Mac 上,但通过 Rosetta(转译层)跑了一个 x64 版本的 OpenWork。这时:

• 应用的架构(App 进程)是 x64(因为装的是 x64 版)
• 系统的架构是 arm64(M 系列原生)

这俩不一致。如果不处理,会出问题——比如自动更新时下错架构的包。

OpenWork 的架构自校正检测这种情况:

检测:appArch(应用架构) vs systemArch(系统架构)
   │
   ├─ 一致 ──► 正常,继续
   │
   └─ 不一致(如 x64 应用跑在 arm64 系统)
        │
        ▼ 生成正确的下载链接(arm64 版)
        │
        ▼ 提示/引导用户换对的版本
​

四、架构自校正的价值

架构不匹配是个隐蔽的坑——应用「能跑」(Rosetta 转译),但:

• 性能差:转译有开销,比原生慢。
• 兼容性问题:某些原生依赖在转译下可能出错。
• 更新会错:自动更新可能继续下 x64 版,永远困在转译。

架构自校正检测这种情况,给用户正确架构的下载链接,引导换原生版。这避免了「用户卡在转译模式不自知」。

💡 为什么这个细节重要:很多应用忽略了 Rosetta 场景,用户装了 x64 版在 M 系列 Mac 上,「能跑但慢」,还不知道为啥。OpenWork 主动检测并引导换原生版,这是用户体验的细致考量。

五、resolveArchitectureInfo 的逻辑

架构自校正的核心是一个架构信息解析逻辑,大致:

resolveArchitectureInfo():
   │
   ├─ appArch = 归一化的应用架构(process.arch)
   ├─ systemArch = 系统真实架构
   │
   ├─ targetArch = 取系统优先(因为原生更好)
   │
   ├─ mismatch = appArch != systemArch?
   │
   ▼ 返回 { appArch, systemArch, mismatch, downloadUrl, releaseUrl, ... }
​

如果 mismatch,downloadUrl 就是「正确架构的下载链接」。这个信息可以用于:

• 启动时检测,提示用户
• 自动更新时选对架构的包

六、品牌图标的跨平台应用(预告)

第 04 节会讲另一个跨平台细节——品牌图标。它和架构自校正类似,都是「跨平台兼容」的工程细节。本节聚焦 CDP 和架构,品牌图标下一节讲。

七、本节要点回顾

1. CDP:Chromium 调试协议,开发/测试/远程调试用。
2. CDP 端口探测:环境变量指定 或 候选列表探测,锁定 127.0.0.1。
3. CDP 必须锁本机:暴露网络=被控制,安全底线。
4. 架构自校正:检测 Rosetta 等架构不匹配,给正确下载链接。
5. 不匹配的坑:能跑但慢/兼容问题/更新会错——用户可能不自知。
6. resolveArchitectureInfo:解析 appArch/systemArch/mismatch/downloadUrl。
7. 细致考量:主动检测引导换原生,不困在转译。

CDP 和架构讲清了,最后一节讲自动更新与品牌图标。