跳到正文

让浏览器插件调用本地能力:Native Host 的边界和协议(1):Native Messaging 通道与宿主选型

让浏览器插件调用本地能力:Native Host 的边界和协议

  1. Native Messaging 通道与宿主选型(当前)
  2. 从 ping 到本机安装与诊断
  3. 能力注册表与权限边界

在浏览器扩展开发里,有些问题纯靠扩展代码解决不了。比如右键复制 GIF 时要写系统级剪贴板,从网页里调用本地 CLI,或者检查本机某个二进制是否安装,这些动作都已经越过了浏览器扩展的沙箱边界。

这种场景可以通过 Chromium 系浏览器提供的 Native Messaging 通信能力处理:扩展声明 nativeMessaging 权限后,浏览器按本机 manifest 找到一个 native messaging host,并通过标准输入输出交换带长度前缀的 JSON 消息。基于这条通道,我们把本机端做成一个通用 native messaging host,让不同浏览器扩展调用同一个程序。Host 按 method 分发剪贴板、诊断等请求;每项能力都需要校验参数和权限,并按统一格式返回结果或错误,后续本地 CLI 调用也可以沿用这条协议。

系列第二篇的 native.ping demo 用 Node.js 实现,可以实际运行。结合项目排查安装、剪贴板和跨浏览器兼容时的体验,当前项目也把 Node.js 定为 Native Host 的主实现;编译型路线保留为后续单文件分发、签名安装器和更强系统 API 封装时的备选。

浏览器通道与本机程序各管一层

浏览器提供的 Native Messaging 通道

Native Messaging 先解决扩展和本机程序之间的基础通信。Chrome 的 Native Messaging 文档和 Microsoft Edge 的 Native Messaging 文档描述的是同一套模型:扩展声明 nativeMessaging 权限,本机提供 host manifest,浏览器按 manifest 找到并启动 host,再通过 stdin / stdout 交换带长度前缀的 JSON 消息。

浏览器负责启动和通信,不负责安装、升级、授权和能力抽象。Native Messaging 打通了入口,但不会自动告诉 host 哪条请求安全、哪个本地命令能执行、文件应该缓存多久、失败时扩展 UI 该提示什么。

浏览器找到 Host 后,按帧交换请求与结果

扩展页面声明 nativeMessaging 权限后,通过 Host 名称发起请求;浏览器查找本机 manifest 并启动程序。最小调用如下:

const hostName = 'fun.shengsheng.native_host_demo';

document.querySelector('#ping').addEventListener('click', () => {
  chrome.runtime.sendNativeMessage(
    hostName,
    {
      id: `ping-${Date.now()}`,
      method: 'native.ping',
      params: {
        from: 'popup',
      },
    },
    (response) => {
      if (chrome.runtime.lastError) {
        console.error(chrome.runtime.lastError.message);
        return;
      }

      console.log(response);
    },
  );
});

Host 累积输入字节,再消费完整帧;stdout 只用于协议,普通日志写 stderr:

while (input.length >= 4) {
  const bodyLength = isLittleEndian ? input.readUInt32LE(0) : input.readUInt32BE(0);
  if (input.length < 4 + bodyLength) return;

  const body = input.subarray(4, 4 + bodyLength);
  input = input.subarray(4 + bodyLength);
  writeResponse(handleRequest(body));
}

消息正文是 UTF-8 JSON,四字节前缀使用本机字节序并记录字节数。正式实现仍需限制消息与缓冲大小、校验非法 JSON 和半帧结束。

调用 Native Messaging 时只传 Host 名称,不能临时指定可执行文件。Windows 需注册 manifest,macOS 则使用浏览器规定目录;这一步仍是本机安装。完整内容见安装与 ping 实操。

商店分发也要落到本机安装

Edge 文档给了两个事实:扩展本身可以像普通扩展一样安装;native apps 不由 Edge 安装或管理。它列出的两种分发模型都依赖本机安装动作:一种是用安装包同时安装扩展和 host;另一种是扩展从 Microsoft Edge Add-ons 安装后,再提示用户安装 host。

Chrome 文档里也有同一个前提:浏览器启动 host 前,必须先能在本机找到 host manifest。其他 Chromium 浏览器如果支持 Native Messaging,也要满足这个前提;差异在于具体商店是否允许在扩展安装后提示用户安装配套程序、安装包能不能同时部署扩展和 host。不能把 Edge 文档里的分发模型理解成所有 Chromium 浏览器都会自动处理本机 host。

开发模式加载文件夹也没有额外的自动安装机制。用户打开 edge://extensions 或 chrome://extensions,加载 unpacked extension,只会让浏览器读取扩展目录;浏览器不会因此复制 host manifest、写注册表或安装本机二进制。开发阶段能做的是把这些动作脚本化:扩展用 manifest.key 固定 ID,安装脚本用这个固定 ID 生成 allowed_origins,最后写 HKCU 注册表,或把 manifest 复制、链接到对应目录。

二进制分发也要覆盖安装层,不能只给一个 exe 或可执行文件。真正可用的包至少要包含:

  • host 二进制。
  • host manifest 生成逻辑或静态样例。
  • Windows 注册表安装逻辑。
  • macOS manifest 复制或符号链接逻辑。
  • 写入 allowed_origins 的扩展 ID。
  • 一个 doctor 命令或能力,用来检查当前安装状态。

如果没有 doctor,用户只能看到扩展报「host not found」或「access forbidden」,很难知道是浏览器没找到 manifest、manifest 里 ID 不对、二进制没执行权限,还是 host 自己启动后崩了。

Native Host 技术选型和跨平台边界

实现层主要落在语言选择、分发方式和能力边界上。Native Messaging 对 host 的要求很朴素:浏览器能启动它,它能按协议读写 stdin / stdout。真正麻烦的是读者怎么跟着跑通、普通用户怎么安装、后续怎么升级,以及 Windows / macOS 上哪些能力需要走系统 API。

编译型和解释型的边界

Node.js、Python、shell、PowerShell、Lua、Rust、Go、C / C++、Swift 都能写 Native Messaging host。只要浏览器能启动对应入口,并且这个入口严格按 Native Messaging 帧格式读写消息,它就可以成为 host。语言选择真正影响的是运行时依赖、安装脚本、调试方式、升级策略、系统 API 调用和跨平台构建成本。

解释型路线包括 Node.js、Python、Lua、shell 和 PowerShell。它的优势是学习和调试成本低,源码可以直接分发,改完就能重跑;如果文章面对前端读者,Node.js 通常也是默认更容易跟做的一条路。Python 和 Lua 也有源码分发优势,但普通 Windows 用户未必已经有稳定运行时;shell 和 PowerShell 很适合做包装器、安装脚本和极小 demo,但复杂协议、缓存生命周期和跨平台剪贴板逻辑继续堆在脚本里,维护成本会很快上来。

解释型路线也有自己的边界。host manifest 的 path 只能指向浏览器要启动的入口,不能把 node xxx.mjs、python xxx.py 这种带参数的命令直接塞进去;Windows 往往还需要 .cmd、小型 exe 或安装器生成的 wrapper,macOS / Linux 则要处理可执行权限、shebang 和隔离属性。源码分发还会把运行时版本、依赖完整性、更新来源和用户机器上的环境差异交给安装逻辑处理。它降低了学习门槛,但安装和信任边界仍然要明确写进 installer、doctor 和 README。

这次 m-chrome-extensions 里最值得留下的一条排障经验,也发生在这个边界上。浏览器扩展只把 host name 交给 Chromium,Chromium 再按注册表和 manifest 去找 path;一旦 launcher 写错、文件不存在、策略不允许,或者包装层启动 Node 的方式不符合当前浏览器预期,扩展侧看到的仍可能只是 host not found。所以 doctor 不能只检查注册表键和值,还要打印当前 manifest 来源、manifest 里的 path、launcher 是否存在、手动 Native Messaging ping 是否能收发帧,以及切换 .cmd / .exe shim 的命令。这样下次看到同一个浏览器原始错误时,排查不会停在「注册表已经写了,为什么还不行」。

编译型路线包括 Rust、Go、C / C++、Swift 和 C# 这类能产出本机程序的方案。它的优势是运行时依赖更少,容易放进安装包,签名、升级和版本诊断也更像传统桌面工具;涉及剪贴板、注册表、系统目录、文件权限和本地 CLI 时,调用系统 API 的边界也更明确。不同语言的安全模型和库生态并不一样,不能把「编译型」直接等同于安全或稳定,但单独分发一个 host 二进制,确实更容易控制用户机器上的前置条件。

编译型路线的成本集中在构建矩阵和发布流程。Windows、macOS Apple Silicon、macOS Intel、Linux 往往都要有对应产物;有些语言可以比较方便地交叉编译,有些目标仍然需要对应平台的 SDK、linker 或构建机。macOS 还会遇到签名、公证、隔离属性和 Apple SDK;Windows 则要处理架构、杀软误报、签名证书和安装器体验。

从 Windows 直接构建 macOS M1 / Intel 产物通常不划算,实际分发更适合用 macOS CI 或 macOS 构建机分别产出。Linux 也需要对应目标链路、glibc / musl 口径和发行包策略,不能只靠本机一次构建解决所有平台。

这次先把 Node.js 定为主实现

在项目的安装与剪贴板排查中,Node.js 的调试体验很直接:改完源码就能重新触发扩展,不需要等跨平台编译;日志、doctor、安装脚本和 Native Messaging 帧读写也能放在同一套语言里迭代。对这类还在验证协议、安装链路和能力边界的工具来说,调试速度比单文件纯净度更重要。

所以当前项目先把 Node.js 定为 Native Host 主实现。Rust、Go、Swift 这类编译型路线仍然有价值,但更适合放到后续分发阶段:当目标变成给大量普通用户安装、需要签名安装器、需要更强的系统 API 封装,或者希望完全摆脱用户机器上的 Node 运行时,再把同一套协议迁移到编译型实现。

Node.js 也不意味着只能写裸 JS。Node.js 的 TypeScript 文档里已经提供了内置 TypeScript 支持,但这条能力主要是类型擦除:它不做类型检查,也不会完整读取 tsconfig.json;遇到 enum、带运行时代码的 namespace、参数属性、路径别名这类需要转换的语法时,仍然要交给第三方工具。开发期如果只写可擦除的 TypeScript,较新的 Node 可以直接跑 .mts;如果希望获得完整 TypeScript 开发体验,当前更适合用 tsx 作为源码运行层。

这样做的好处是不用在每次改完 host 后先跑一遍构建。源码分发时,Windows 的 .cmd 和 macOS 的 .sh 仍然只是很薄的 wrapper,真正入口可以落到 native-node 包里的 TypeScript 文件;安装逻辑先确认 Node、pnpm 和依赖状态,再生成 host manifest、写注册表或创建 manifest 链接。等到面向普通用户分发时,再把同一套源码 bundle 成 JS,或者连 Node 运行时一起放进安装包里。

第二篇的 native.ping demo 保持零运行时依赖,用来减少通信排查变量;项目里的 TypeScript runner、安装工具和完整能力实现是另一层依赖。后续剪贴板、MIME、缓存或 schema 校验需要第三方包时,可以正常加入相应包的 dependencies,不用为了「零依赖」自己重写系统能力。

源码分发可以在安装阶段执行 pnpm install --frozen-lockfile,或者在发现依赖缺失时给出明确命令;打包分发则把依赖和入口一起 bundle,用户不需要理解 workspace 和包管理器。需要单独评估的是带原生 addon、postinstall 下载二进制或依赖额外系统库的包,它们会把问题重新带回平台矩阵和安装诊断里。

Node 后续也有几种分发形态。最轻的是源码包加安装脚本,适合开发者和教程读者;再往前一步,是 bundle 后的 JS 加一份随包携带的 Node 运行时,使用体验接近 Electron 这类跨平台工具;更进一步可以研究 Node.js Single executable applications,把程序注入到 Node 可执行文件里。SEA 还处在 active development,当前约束也更多,适合等协议和能力边界稳定以后再评估。

Monorepo 影响组织和分发,不影响协议

m-chrome-extensions 现在是 pnpm workspace。扩展放在 apps/*,通用包放在 packages/*,Native Host 分成 native-node 和 native-rust 两条实现线。这种目录组织决定源码与安装入口放在哪里;浏览器仍然只认 host name、host manifest、allowed_origins 和 manifest 里的 path。

monorepo 的好处是扩展、host、共享协议和 demo 能一起演进。后面如果把 { id, method, params, result, error }、错误码、能力 schema、Extension ID 常量抽到 packages/*,扩展侧和 host 侧可以复用同一套类型定义;native-node 可以专注 host、installer、doctor 和剪贴板能力;native-rust 可以保留为后续编译型验证,不干扰当前 Node 主线。

它也会改变安装脚本要承担的责任。开发期的 manifest 可以指向 workspace 里的 wrapper,但安装脚本不能依赖用户当前命令行所在目录,应该从 import.meta.url 或包目录推导真实路径。源码分发时,安装入口可以在仓库根目录执行 pnpm install --frozen-lockfile,再跑 pnpm --filter @m-chrome-extensions/native-node install:host;如果直接分发给普通用户,最终包就应该输出一个自包含目录,让 manifest 指向包内 wrapper,而不是要求用户保留完整 monorepo。

协议仍然保持语言无关

Native Messaging 的协议层不绑定具体语言。扩展侧发出的仍然是结构化 JSON 请求,例如 { method, params, id };Host 侧返回的仍然是结构化结果,例如 { ok, result, error }。只要这层协议稳定,上层扩展、安装诊断和能力文档就不必因为实现语言变化而重写。

Host 内部也可以保持同样的分层。协议层只处理 Native Messaging 帧格式和 JSON 解析;能力层只接收已经校验过的请求,不直接读 stdin;安装层只负责 manifest、注册表、浏览器目录和执行权限,不和业务 handler 混在一起。当前用 Node.js 写,是为了让这几层更快被调试和验证;后续如果迁移到 Rust、Go 或 Swift,应该迁移的是实现,不是扩展和 host 之间的业务协议。

一次读取可能只有半帧,也可能含多帧

Windows 兼容还要额外注意几个点:

  • stdin / stdout 要按二进制模式处理,避免换行转换破坏 4 字节长度前缀。
  • 写注册表时同时考虑 Chrome 和 Edge 的 Native Messaging host 路径。
  • 写剪贴板文件列表时使用 Unicode 路径,并确保文件在目标应用读取前仍然存在。
  • 编译型路线要明确目标架构和签名策略;解释型路线要明确运行时路径、wrapper 和依赖检查。
  • 安装脚本默认写用户级目录,避免一开始就要求管理员权限。

macOS 则重点在 manifest 目录、执行权限、签名 / 隔离属性和 Pasteboard 写入方式。第一版可以先做用户级安装,把 host 放到 ~/Library/Application Support/<APP_NAME>/,manifest 放到对应浏览器目录。后续如果要给不熟悉命令行的用户用,再考虑 .pkg、.app 或带双击入口的安装包。

选型后的下一步

浏览器只负责按名称启动已注册的宿主,并提供字节通道。实现语言、运行时随包方式和跨平台安装由项目决定。选择 Node.js 后,可以继续按安装篇用一个 ping 检查权限、manifest、launcher 和消息帧;能力协议则在第三篇展开。