跳到正文

让浏览器插件调用本地能力:Native Host 的边界和协议(2):从 ping 到本机安装与诊断

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

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

这个最小示例用 Node.js 实现一个 Native Messaging Host,让浏览器扩展发送 native.ping 并取得 pong。扩展与 Host 是两个程序:前者加载到浏览器,后者安装到当前用户的系统位置。先跑通一次往返,再按 Windows/macOS 的查找规则排错;完整源码在配套工作区中。

名称先找到 manifest,再找到启动入口

用 native.ping 跑通 demo

这个 demo 做的事很小:点击扩展 popup 里的按钮,扩展页面向 fun.shengsheng.native_host_demo 发送 native.ping,浏览器按本机 host manifest 启动 Native Host,Native Host 从 stdin 读取请求,再从 stdout 写回 pong。它验证的是扩展权限、host manifest 注册、浏览器启动本机程序、Native Messaging 帧格式和一问一答响应结构。

插件侧有两个动作:声明 nativeMessaging 权限,发起 sendNativeMessage() 调用。为了让 demo 能直观看到结果,action.default_popup 再挂一个 popup 页面。popup 属于扩展页面,可以直接调用 chrome.runtime.sendNativeMessage();如果请求来自 content script,则要先转给 service worker 或扩展页面。

{
  "manifest_version": 3,
  "name": "Native Host Demo",
  "version": "0.1.0",

  // 允许扩展页面调用 chrome.runtime.sendNativeMessage() / connectNative()。
  "permissions": ["nativeMessaging"],

  // 工具栏按钮打开 popup,便于手动发起 native.ping 并查看响应。
  "action": {
    "default_title": "Native Host Demo",
    "default_popup": "popup.html"
  }
}

真实的 manifest.json 只支持 JSON,不能保留注释。这里用 json5 代码块,是为了把字段解释贴在字段旁边;复制到真实项目时要删除注释,或者直接使用后面源码包里的 JSON 文件。

popup 里发请求的逻辑也很直接:

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);
    },
  );
});

Native Host 侧对应两件事:提供 host manifest,让浏览器知道 fun.shengsheng.native_host_demo 对应哪个本机入口;入口程序按 Native Messaging 协议读写消息。

host manifest 是浏览器寻找本机程序的索引文件,用来声明 Native Host 的名称、入口路径、通信方式和允许调用它的扩展来源。Windows 上可以把这个 JSON 放在应用自己的安装目录里,再让注册表指向它;macOS / Linux 则要把它放进浏览器约定的 NativeMessagingHosts/ 目录。README 里可以保留一段静态样例帮助读者理解字段,真正安装时再写入本机实际路径和允许调用的扩展来源。

{
  // 扩展调用 runtime.sendNativeMessage() / connectNative() 时传入的 host 名称。
  // 名称只能使用小写字母、数字、下划线和点。
  "name": "fun.shengsheng.native_host_demo",

  "description": "Native Host Demo",

  // 浏览器真正要启动的本机入口。Windows 可以指向 .cmd 或 exe wrapper,
  // macOS / Linux 通常指向有可执行权限的 shell wrapper 或二进制。
  "path": "C:\\Users\\me\\AppData\\Local\\ShengNativeHostDemo\\native-host.cmd",

  // Native Messaging 目前就是通过 stdin / stdout 通信。
  "type": "stdio",

  // 允许调用这个 host 的扩展来源,格式必须带 chrome-extension:// 和末尾斜杠。
  "allowed_origins": ["chrome-extension://dhomoolooollmopglnjkeciabhibjjfp/"]
}

真实的 host manifest 同样只支持 JSON,不能保留注释。开发阶段可以把带注释的版本当说明文档,安装脚本实际写入的是去掉注释后的 JSON。

native-host.mjs 不依赖 npm 包,只处理 native.ping。关键片段用于解释帧协议,完整文件可在配套源码工作区中查看。

Native Messaging 只规定字节帧格式,id、method、ok、result、error 是 demo 自己定义的业务协议。完整实现放在 Code Lab;这里先看从缓冲区取出一帧的关键部分:

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 字节计算

一次 data 事件可能只有半帧,也可能包含多帧,所以先累积 Buffer,再循环消费完整消息。handleRequest 解析 UTF-8 JSON,仅为 native.ping 返回 pong;writeResponse 把响应编码成 UTF-8,按正文的字节数写 4 字节本机字节序前缀,然后写正文。这里不能用 JS 字符串的 length 代替 UTF-8 字节数。普通日志写 stderr,否则会污染浏览器读取的 stdout 协议。

这个 demo 用于跑通通信。正式协议层还需限制单条消息和累积缓冲大小,校验请求结构、非法 JSON 与半帧 EOF,并遵守浏览器各方向的消息上限。大文件走受限分片或缓存,不直接塞进一条 JSON。

Windows 和 macOS 都还需要一个很薄的入口包装。浏览器启动的是 host manifest 里的 path,不能在 path 里直接写 node native-host.mjs 这种带参数的命令;所以 demo 里给 Windows 准备了 .cmd 和 ps1,给 macOS 准备了 .sh。

Windows 的 launcher 是独立兼容层。真实项目排查时,manifest 里的 path 一度指向 .exe wrapper,注册表和 host manifest 看起来都存在,但 Chrome / Edge 仍然报 Specified native messaging host not found.。后来把开发态默认入口改成 .cmd,再由 .cmd 启动 Node.js 脚本,浏览器侧才稳定连上。因此,解释型 Native Host 在 Windows 上要把 launcher 当成可替换层:开发阶段优先选可读、可改、容易打日志的入口,正式分发阶段再评估签名 .exe shim、安装器或单二进制。

源码包里把这两类文件分开了:native-host/src/ 放 Native Host 运行时代码和浏览器实际启动的 wrapper;native-host/install/ 放安装器和平台注册逻辑。读源码时,可以先看 src/native-host.mjs 理解协议,再看 install/index.mts 和 install/utils/ 理解它如何落到 Windows 注册表和 macOS manifest 目录。

完整源码我放成了一个可下载 demo 包:

native-host-demo/
  README.md
  extension/
    manifest.json
    popup.html
    popup.css
    popup.js
  native-host/
    src/
      native-host.mjs
      native-host.cmd
      native-host.ps1
      native-host.sh
    install/
      index.mts
      install-windows.ps1
      install-macos.sh
      utils/
        args.mts
        constants.mts
        manifest.mts
        shared.mts
        windows.mts
        unix.mts
完整源码工作区弹窗可按文件浏览 demo。这个 Code Lab 只展示源码,不会在页面里运行 Native Messaging;真正验证还需要按 README 加载扩展并安装本机 host。

真正运行前,需要先把 extension/ 加载进浏览器,再执行安装脚本。demo 的 extension/manifest.json 已经写入固定 public key,Edge / Chrome 加载这个 unpacked extension 时会得到同一个 Extension ID:dhomoolooollmopglnjkeciabhibjjfp。安装脚本也默认把这个 ID 写进 allowed_origins,读者不用再从扩展管理页复制 ID。

Extension ID 是浏览器给扩展生成的 ID。没有固定 key 时,开发模式加载 unpacked extension 得到的 ID 不适合直接当成跨机器、跨浏览器、跨发布渠道的固定值。Chrome 文档提供了 "key" 字段,让开发期扩展 ID 从同一把公钥派生出来;Chromium 源码里的 ID 生成逻辑 会取公钥 SHA-256 的前 16 字节,再映射成 a-p 字母。Edge 文档也提醒,扩展发布到 Add-ons 后,正式 ID 可能和 sideload 阶段不同,因此商店分发时仍要以商店里的正式 ID 更新 allowed_origins。

Windows:

.\native-host\install\install-windows.ps1

macOS:

./native-host/install/install-macos.sh

两个入口都会调用 native-host/install/index.mts,由它解析参数、根据本次源码包中 native-host/ 的实际位置生成 JSON manifest,再选择平台分支。Windows 注册表逻辑在 install/utils/windows.mts,macOS / Linux 的 manifest 目录和符号链接逻辑在 install/utils/unix.mts;具体注册位置和诊断方式在本篇的 Windows/macOS 安装逻辑中继续展开。

README 里保留了一段静态 host manifest 样例,但它只是说明,不参与安装流程。真实给浏览器读取的 manifest 会在安装时生成到 native-host/install/fun.shengsheng.native_host_demo.json,里面包含当前机器上的绝对路径和当前扩展 ID。

对于 360、QQ、Dia 这类 Chromium 变体,脚本会先看本机是否存在对应安装痕迹;检测到以后,再写入一组候选位置。回到扩展管理页点 Reload,再打开 popup 点 Ping Native Host,就能看到 pong、扩展 origin、系统平台和 Node.js 版本。

macOS 这里用符号链接只是 demo 的安装方式,不是 Native Messaging 的新机制。浏览器要求的是固定目录里能读到 <HOST_NAME>.json;正式安装器也可以选择复制 JSON 文件。Windows 直接执行 .ps1 时可能被本机 Execution Policy 拦截;遇到这种情况,可以临时用 powershell -ExecutionPolicy Bypass -File .\native-host\install\install-windows.ps1 跑 demo。macOS 从 zip 解压后如果丢了可执行权限,先执行 chmod +x ./native-host/install/install-macos.sh。

这段代码只适合解释 sendNativeMessage() 的一问一答流程;真实项目应该把读写帧封装成单独模块。如果用 connectNative() 保持长连接,host 需要在循环里持续读帧,直到 stdin 关闭或出现不可恢复错误。一问一答适合复制一次文件、查询一次版本、跑一次 doctor;需要保持会话、连续收发多条消息时,再用 connectNative() 建立长连接。

安装逻辑

Native Messaging 的调用入口只有 host 名称。扩展声明 nativeMessaging 权限后,可以调用 runtime.sendNativeMessage('com.example.native_host', message),但不能在调用时临时传入本机可执行文件路径。浏览器会用这个 host 名称去系统里查找同名 host manifest,再由 host manifest 指向真正要启动的本机程序。

因此安装 Native Host 的核心工作,是把本机程序和浏览器能读取的索引文件对应起来。demo 里的安装脚本会用固定 Extension ID 生成 allowed_origins,把真实入口路径写进 host manifest,再按平台差异把浏览器指向这份 manifest。

Windows 用户级安装

Windows 上,浏览器通过注册表找到 host manifest。这个 JSON 文件可以放在任意位置,注册表默认值指向它即可。demo 里直接把生成出来的 fun.shengsheng.native_host_demo.json 放在 native-host/install/ 目录下;正式分发时,我倾向于把 manifest 和 host 二进制放在同一个应用目录,例如:

%LOCALAPPDATA%\ExampleHost\com.example.native_host.json
%LOCALAPPDATA%\ExampleHost\native-host.exe

这样安装、升级和卸载都只围绕一个目录处理。即使 Windows 允许 path 相对 manifest 文件所在目录,实际分发时也建议写成绝对路径,减少安装器工作目录、快捷方式启动和调试脚本带来的差异。

Chrome 的用户级注册表位置是:

HKCU\Software\Google\Chrome\NativeMessagingHosts\<HOST_NAME>

Edge 有自己的注册表位置:

HKCU\Software\Microsoft\Edge\NativeMessagingHosts\<HOST_NAME>

注册表默认值写的是 host manifest 的完整路径,不是 host 二进制路径。Edge 找 manifest 时还有一条容易忽略的顺序:它会先查自己的注册表位置,再继续查 Chromium 和 Chrome 的位置;只要前面的某个位置命中,就不会继续往后查。一个同时支持 Chrome Web Store 和 Microsoft Edge Add-ons 的工具,最好明确给 Chrome 和 Edge 都写注册表,并把两个商店对应的扩展 ID 都放进 allowed_origins。

360、QQ 这类 Chromium 浏览器的情况要分开看:如果它复用 Chrome / Chromium 的 Native Messaging 注册表位置,默认安装脚本已经覆盖;如果本机已经存在对应的 NativeMessagingHosts 注册表根,脚本会扫描并写入;如果检测到常见的 360、QQ、Dia 安装痕迹,脚本也会写入一组候选注册表根。仍然失败时,通常说明这个浏览器使用了脚本不知道的私有路径,需要把真实根路径传给 -RegistryRoot。

开发阶段可以用一条用户级命令先跑通 Chrome:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.example.native_host" /ve /t REG_SZ /d "C:\Users\me\AppData\Local\ExampleHost\com.example.native_host.json" /f

这条命令写的是当前用户的注册表,不需要把 host 装到系统目录;Edge 只是换成 HKCU\Software\Microsoft\Edge\NativeMessagingHosts\<HOST_NAME>。

写完注册表以后通常不需要重启电脑。浏览器在下一次启动 native host 时会按注册表和 manifest 查找;开发阶段重新触发一次 sendNativeMessage(),或者在扩展管理页点 Reload 后再试,一般就能看到新配置。已经建立的 connectNative() 长连接不会因为 manifest 改了自动重连;这种情况下先断开连接、重载扩展,必要时重启浏览器进程。排查时优先重载扩展或重启浏览器,不把重启系统当成默认步骤。

很多 Windows 教程写完注册表后会建议重启,是因为 Explorer、系统服务、文件关联、驱动或策略缓存都可能长时间持有旧配置。Native Messaging 这条链路的读取点更窄:浏览器启动 host 时按 host 名称查注册表,再读取 manifest。配置写错时,重载扩展、断开已有 native port 或重启浏览器进程通常已经足够;重启电脑只是排查缓存和残留进程的兜底动作。

macOS 用户级安装

macOS 不用注册表。用户级安装就是让浏览器用户数据目录下的 NativeMessagingHosts/ 子目录里出现 <HOST_NAME>.json,并确保 manifest 里的 path 指向可执行的 host 入口。例如 Chrome stable 是:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/<HOST_NAME>.json

Edge stable 是:

~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/<HOST_NAME>.json

Dia 和其他 Chromium 浏览器也是同一个问题:如果它们使用自己的 Native Messaging manifest 目录,安装脚本需要知道那个目录。demo 脚本会扫描 ~/Library/Application Support 下已经存在的 NativeMessagingHosts 目录;检测到 Dia、QQ、360 这类常见变体时,也会写入对应候选目录。需要强制指定时,可以执行 ./native-host/install/install-macos.sh --browser dia、./native-host/install/install-macos.sh --browser qq 或 ./native-host/install/install-macos.sh --browser 360;其他浏览器可以用 --manifest-dir 指到自己的目录。默认模式会在这些目录里创建指向生成 JSON 的符号链接;如果想复制真实文件,可以加 --copy-manifest。

从使用成本看,Windows 的「安装感」会更明显,因为需要写 HKCU 或 HKLM 注册表;macOS 是让 manifest 出现在浏览器固定目录,可以复制文件,也可以用符号链接指向同一份生成 JSON。Linux 也是固定目录思路,如果后续要支持,需要再补对应发行包和路径检查。HKCU 是当前用户级注册表,通常不需要管理员权限,比 HKLM 轻一些,但仍然是一次注册动作。

怎样确认真正跑通

浏览器 popup 收到 pong,才能同时证明扩展权限、Host 名称、allowed_origins、系统注册、启动包装和字节帧链路成立。安装脚本退出成功,只说明脚本完成了自己的工作。遇到 host not found,应逐层核对索引文件与入口;收到无效消息,则先检查 stdout 是否混入日志、长度是否按 UTF-8 字节计算。

Native Host 的完整 ping demo:完整源码
Native Host Demo 源码正在加载代码工作区...