nexus
适配器

Chrome 扩展

配置扩展上下文,精确连接后台脚本、内容脚本或应用寻址的扩展页面。

@nexus-js/chrome 用于连接 Chrome 扩展中的各个上下文。使用对应的辅助函数初始化:usingBackgroundScript()、usingContentScript()、usingPopup() 等。

pnpm add @nexus-js/core @nexus-js/chrome

快速开始指南演示如何定义共享契约、在后台提供服务,并从内容脚本调用。

精确连接目标

使用 chromeTarget 指定后台脚本、框架、文档、内置页面或自定义扩展页面:

import { chromeTarget } from "@nexus-js/chrome";

const exactBackground = chromeTarget.background();
const exactContent = chromeTarget.contentDocument({
  tabId: 42,
  documentId: "document-1",
});
const exactOffscreen = chromeTarget.offscreenDocument();
const exactPopup = chromeTarget.popup({ windowId: 42 });
const exactPanel = chromeTarget.sidePanel({ windowId: 42 });
const exactOptions = chromeTarget.optionsPage();
const exactDevTools = chromeTarget.devToolsPage({ inspectedTabId: 42 });
const exactCustomPage = chromeTarget.extensionPage({ endpointId: "settings" });

例如,应用确定目标文档后,已配置的后台上下文可以连接它并获取服务:

import { chromeTarget, usingBackgroundScript } from "@nexus-js/chrome";
import { CaptureToken } from "./shared-contracts";

const backgroundNexus = usingBackgroundScript();
const tabId = 42;
const documentId = "document-1";

const connection = await backgroundNexus.connect({
  target: chromeTarget.contentDocument({ tabId, documentId }),
  where: (contextMeta) =>
    contextMeta.context === "content-script" && contextMeta.isVisible === true,
});
const capture = connection.get(CaptureToken);

应用负责选择当前标签页、注入内容脚本,再将得到的地址交给 Nexus。 tabId、frameId 和 documentId 是平台地址。经过验证的发送方信息通过 ChromeConnectionMeta 提供,与对端自行声明的身份分开保存。Chrome 只在 incoming Port 上提供 Port.sender;outgoing 连接选中的目标由 adapter 私下保存,不会伪装成 where 可验证的 observed.documentId。

内容脚本初始化函数不会自动选择服务所在的连接目标。需要连接后台时,将 chromeTarget.background() 传给 connect。

内置页面与自定义页面

内置页面 receiver helper 会独立识别本地 Chrome 上下文,与 caller 侧 target 选择分开。其他上下文需要主动连接某个实例时,使用对应的精确 target:

内置上下文Receiver helperCaller targetCaller 侧精确坐标
BackgroundusingBackgroundScript()chromeTarget.background()无
Content ScriptusingContentScript()chromeTarget.contentFrame({ tabId, frameId }) 或 chromeTarget.contentDocument({ tabId, documentId })tabId 加 frameId 或 documentId
PopupusingPopup()chromeTarget.popup({ windowId })windowId
Options PageusingOptionsPage()chromeTarget.optionsPage()无;profile 指定 receiver
DevTools PageusingDevToolsPage()chromeTarget.devToolsPage({ inspectedTabId })inspectedTabId
Offscreen DocumentusingOffscreenDocument({ reason })chromeTarget.offscreenDocument()无;profile 单例
Side PanelusingSidePanel()chromeTarget.sidePanel({ windowId })windowId

例如,Side Panel 入口不需要自行发明应用路由:

const panelNexus = usingSidePanel();

后台、内容脚本或另一个扩展页面使用对应的结构化页面地址连接:

const connection = await nexus.connect({
  target: chromeTarget.sidePanel({ windowId: 42 }),
});

离屏文档使用单例 target 接收连接:

const offscreenNexus = usingOffscreenDocument({
  reason: "audio-processing",
});

const connection = await backgroundNexus.connect({
  target: chromeTarget.offscreenDocument(),
});

Side Panel helper 会在内部识别当前浏览器窗口中正在运行的 Side Panel。Caller 侧 target 选择浏览器窗口。Chrome 的 tab-specific/global panel 配置仍属于应用 UI 配置;Nexus 面向某个窗口中当前运行的 Side Panel receiver,不提供按 tabId 寻址的 Side Panel target。结构化坐标是路由输入,不是身份或授权信息。

其他内置 helper 同样不会要求调用者重复填写 receiver 的路由事实: usingPopup() 通过 windows.getCurrent() 解析当前 windowId, usingDevToolsPage() 读取 chrome.devtools.inspectedWindow.tabId, usingContentScript() 使用 Chrome 提供的 native frame/document 路由。 usingOptionsPage() 表示 profile 指定的 Options receiver, usingOffscreenDocument({ reason }) 表示 profile 单例。helper 的自动识别与 caller 侧 target 选择是两件独立的事。 同一时间只有一个 usingOptionsPage() receiver 可以持有 profile target;第二个 Options 页面会明确地在 ready 阶段失败,owner 关闭后 replacement 才能接管。

打开或聚焦 Popup、Options、Side Panel,创建 Offscreen Document,打开 DevTools, 以及注入 Content Script 都是独立的应用或 Chrome 生命周期操作。 connect({ target }) 只获取或拨号到已经创建且 ready 的 receiver,不执行这些操作。 Popup 每次重新打开都会创建新的 session,旧页面关闭后必须重新连接。

自定义扩展页面没有 adapter 管理的结构化地址。只有 usingExtensionPage 或 createExtensionPageConfig 使用应用管理的 endpointId,并通过 chromeTarget.extensionPage({ endpointId }) 连接:

const settingsNexus = usingExtensionPage(
  { context: "settings-page" },
  { endpointId: "settings" },
);

const settingsConnection = await contentNexus.connect({
  target: chromeTarget.extensionPage({ endpointId: "settings" }),
});

连接建立后,页面仍通过 context: "side-panel"、context: "offscreen-document" 等 ContextMeta 表达远端身份。Target 负责路由,ContextMeta 负责身份,policy 负责授权。

职责边界如下:

  • 应用负责选择 caller 侧目标实例:发现精确 target 所需的 windowId、inspectedTabId、tabId、frameId 和 documentId,只为自定义页面分配 endpointId,创建页面并等待页面就绪。Receiver helper 在 Chrome 能提供事实时独立完成本地自动识别。
  • Chrome adapter 负责执行和约束平台路由:将明确的 target 转换为 runtime.connect() 或 tabs.connect(),并拒绝当前上下文不支持的连接。
  • Nexus Core 负责 native Port 选定后的握手、授权、Connection 生命周期、RPC 和 Relay。

应用必须保证自定义页面的 endpointId 唯一。地址只是 native Port name 中的本地路由标签,不是身份或授权凭据。Nexus 不会自动发现或创建缺失的页面。

连接能力

本地上下文可以主动连接的目标
Background精确 Content Frame/Document、内置页面、自定义扩展页面
ISOLATED Content ScriptBackground、内置页面、自定义扩展页面
Popup、Options、Side Panel、DevTools、普通扩展页面Background、内置页面、自定义扩展页面、精确 Content Frame/Document
Offscreen DocumentBackground、内置页面、自定义扩展页面

连接建立后可以双向通信。Content Script 和 Offscreen Document 不能主动调用 tabs.connect() 连接 Content Script;需要中间节点时,显式提供 Relay,不会自动进行透明多跳路由。

多个连接

使用 connectMulticast 获取已可用连接的快照,然后从每个成员取得服务:

const captures = await backgroundNexus.connectMulticast({
  where: (contextMeta, _connectionMeta) =>
    contextMeta.context === "content-script" && contextMeta.isVisible === true,
});
const resources = captures.get(CaptureToken);

如果需要 Nexus 主动获取连接,直接提供 targets,无需先为每个目标调用 connect。 所有目标必须连接成功,但每个成员上的服务获取仍分别返回 Result。可以一起处理服务缺失和调用失败:

const outcomes = await Promise.allSettled(
  resources.map(async ({ result }) => {
    if (result.isErr()) throw result.error;
    return await result.value.capture();
  }),
);

示例假定共享的 CaptureToken 契约声明了 capture()。直接组合原生 Promise 即可,无需额外的多播代理或结果报告类型。

会话生命周期

页面跳转或上下文销毁会使相关代理和引用失效。应监听已获取的连接,并在新上下文就绪后重新获取连接与代理;参阅连接生命周期。

按框架位置寻址时,使用框架目标;操作必须绑定某一份文档时,使用文档目标。同一流程应保持寻址方式一致:框架目标与文档目标并不等价,交替使用它们访问同一上下文可能建立多个会话。 页面跳转后,文档目标不会自动指向新文档。

离屏文档可以连接 Background 或页面 target。应用负责调用 chrome.offscreen.createDocument() 并确认页面就绪; usingOffscreenDocument({ reason }) 只配置 Nexus,不创建页面。类似地, runtime.openOptionsPage()、Popup 创建、Side Panel 激活和 DevTools 打开都是独立的 生命周期操作;target acquisition 不会执行这些操作。

传输限额

在 Google Chrome 152+ 中,MV3 扩展在 manifest.json 开启 Structured Clone 消息序列化后, 适配器会自动启用二进制数据包:

{
  "manifest_version": 3,
  "message_serialization": "structured_clone"
}

适配器通过 navigator.userAgentData.brands 检查 Google Chrome 品牌和主版本, 并读取 manifest 配置。旧版本、其他浏览器品牌、缺少 Client Hints 或未开启该配置时, 使用 JSON 数据包和 Base64 二进制附件。两条路径都支持 RPC 二进制值。 二进制数据包采用复制语义,不支持 transferable。数据包模式自动选择,不开放 binaryPackets 配置。

可通过 helper 的 transport 选项配置帧、消息和聚合缓冲限额; 默认值分别为 64 KiB、16 MiB 和 64 MiB:

usingBackgroundScript({
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
  },
});
在 GitHub 上编辑此页