浏览器插件这个领域，过去很多年都被当成"前端边角料"——写个 content script 往页面里塞点 DOM，再配个 popup 弹窗，基本就能交差。但这两年情况完全变了。Chrome 全面推行 Manifest V3 之后，后台页被 Service Worker 取代，插件的生命周期、通信模型、资源加载方式全部重写；与此同时，端侧 AI 的推理能力开始往浏览器里下沉，插件不再只是"改改页面样式"的小工具，而是要承担模型加载、跨进程数据流转、离线推理调度这些实打实的工程任务。我最近完整地把一个带端侧 AI 能力的 MV3 插件从零搭到上线，中间踩的坑比过去三年加起来都多。这篇就把 MV3 架构、跨进程通信、端侧 AI 集成这三块串起来讲清楚，适合已经写过基础插件、想往工程化方向走的人，也适合被 Service Worker 生命周期折磨过的同行对照排查。
1. MV3 到底改了什么：从常驻后台到事件驱动的范式切换
很多人对 MV3 的抵触，本质上不是讨厌新 API，而是没接受"后台不再常驻"这个事实。MV2 时代 background page 是一个一直活着的页面，你可以把全局变量、定时器、长连接都挂在上面，随用随取。MV3 把这块换成了 Service Worker，它会在空闲时被浏览器杀掉，下次事件触发再重新拉起。这个变化不是优化，是范式切换，理解不到位后面全是坑。
1.1 Service Worker 的生命周期为什么是核心矛盾
Service Worker 的存活逻辑可以类比成"随叫随到的临时工"：有事件（比如收到消息、点击图标、网络请求拦截）就唤醒，干完活大约 30 秒没新事件就被回收。官方文档给的闲置回收时间是 30 秒，但实测下来这个值并不稳定，负载高的时候可能更短。这意味着任何依赖"内存里存着某个状态"的写法都会随机失效。
我最初写的一个功能是：用户点击插件图标开始一个持续几分钟的数据采集任务，用setInterval每 5 秒抓一次数据。在 MV2 里跑得好好的，迁到 MV3 后任务经常跑到一半就断了。原因很直接——Service Worker 被回收，setInterval连同它的回调一起消失。正确的做法是把长任务拆成由chrome.alarms驱动的离散事件，每次唤醒只做一小步，状态落到chrome.storage里。
// 错误示范：依赖常驻内存的定时器 let counter = 0; setInterval(() => { counter++; collectData(counter); }, 5000); // 正确做法：用 alarms 驱动，状态持久化 chrome.alarms.create('collect', { periodInMinutes: 0.1 }); chrome.alarms.onAlarm.addListener(async (alarm) => { if (alarm.name !== 'collect') return; const { counter = 0 } = await chrome.storage.local.get('counter'); await collectData(counter); await chrome.storage.local.set({ counter: counter + 1 }); });这里有个细节值得说：chrome.alarms的最小周期在打包发布的插件里被限制为 1 分钟（periodInMinutes最小值 1），只有在未打包加载的开发模式下才能用更短的值。所以如果你的任务需要秒级精度，alarms 并不合适，得换思路——要么用chrome.runtime.connect维持一个长连接端口（port 存在时 SW 不会被回收），要么把高频逻辑挪到 offscreen document 里。
1.2 全局状态该往哪儿放：storage、offscreen 与内存的取舍
状态管理是 MV3 工程化的第一道分水岭。我把常见状态按"存活需求"分了三类，对应三种存放位置，这张表是我实际项目里总结出来的：
| 状态类型 | 典型例子 | 推荐存放位置 | 原因 |
|---|---|---|---|
| 跨会话持久状态 | 用户配置、采集进度 | chrome.storage.local | SW 重启后仍可读，容量默认 10MB（可申请 unlimitedStorage） |
| 会话内临时状态 | 当前任务 ID、临时 token | chrome.storage.session | 浏览器关闭即清，不落盘，适合敏感临时数据 |
| 高频计算/长任务 | 模型推理、音视频处理 | offscreen document | 有独立 DOM 和完整生命周期，不受 SW 回收影响 |
chrome.storage.session是 MV3 后期才补上的 API，很多人还不知道。它默认只在内存里，浏览器重启就没了，非常适合放那种"不想写进磁盘但又需要跨 SW 唤醒周期保留"的数据。我那个采集任务的任务 ID 就放在 session 里，避免每次 SW 重启都重新生成导致任务对不上。
至于 offscreen document，它是 MV3 里被严重低估的能力。它本质上是一个隐藏的扩展页面，能访问 DOM、能跑 Web Worker、能用URL.createObjectURL，生命周期由你手动控制（chrome.offscreen.createDocument/closeDocument）。端侧 AI 的模型推理我最后就是放在 offscreen 里跑的，原因后面第 3 节细说。
1.3 资源加载与 CSP：那些突然报错的远程脚本
MV3 另一条硬性限制是内容安全策略（CSP）收紧：扩展页面里不允许执行远程代码，eval、new Function、远程<script src>全部被禁。这条规则直接干掉了一大批"从 CDN 拉个库动态执行"的写法。
我遇到的具体问题是：端侧 AI 用的推理库需要加载 WASM 文件，最初我图省事从远程地址拉，结果控制台报Refused to load the script because it violates the following Content Security Policy directive。解决办法是把 WASM 和模型文件全部打包进扩展，用chrome.runtime.getURL()拿本地路径。
// 打包进扩展的 WASM 路径获取 const wasmUrl = chrome.runtime.getURL('wasm/inference_bg.wasm'); const modelUrl = chrome.runtime.getURL('models/model.onnx'); // 注意：manifest 里要声明 web_accessible_resources对应的 manifest 配置：
{ "web_accessible_resources": [ { "resources": ["wasm/*", "models/*"], "matches": ["<all_urls>"] } ] }提示：
web_accessible_resources在 MV3 里改成了对象数组格式，必须显式声明matches，否则资源无法被 content script 或页面访问。这个格式变化是迁移时的高频报错点。
还有个容易忽略的点：WASM 的加载在 MV3 里对wasm-unsafe-eval有依赖。如果你的推理库用到了动态编译 WASM，需要在 manifest 的content_security_policy.extension_pages里加上'wasm-unsafe-eval'，否则会静默失败。这个报错信息很不友好，我第一次排查花了整整一个下午。
2. 跨进程通信：content script、SW 与 offscreen 之间的数据怎么走
MV3 插件的进程模型比 MV2 复杂得多：content script 跑在网页的渲染进程里，Service Worker 跑在扩展自己的进程里，offscreen document 又是另一个独立上下文。这三者之间传数据，是工程化里最容易出 bug 的地方。我见过太多插件因为通信没设计好，出现消息丢失、重复处理、状态不一致的问题。
2.1 三种通信方式的适用边界
先把可选的通信手段列清楚，别一上来就无脑用chrome.runtime.sendMessage：
chrome.runtime.sendMessage/onMessage：一次性请求-响应，适合短消息。缺点是 SW 没醒的时候消息可能丢，且不支持流式。chrome.runtime.connect/onConnect（长连接 Port）：建立持久通道，适合需要多次往返或流式传输的场景。关键优势是——只要 Port 还连着，SW 就不会被回收。chrome.storage的onChanged事件：间接通信，适合"广播状态变更"而不是"点对点传消息"。
我那个端侧 AI 插件的架构是这样的：content script 负责从页面提取待处理文本，通过长连接 Port 发给 SW，SW 转发给 offscreen 做推理，推理结果再原路返回。为什么用长连接而不是 sendMessage？因为推理是异步且可能耗时的，用 Port 能保证 SW 在整个推理期间不被回收，同时支持进度回传。
// content script 侧：建立长连接 const port = chrome.runtime.connect({ name: 'inference' }); port.postMessage({ type: 'infer', text: extractedText }); port.onMessage.addListener((msg) => { if (msg.type === 'progress') updateProgressUI(msg.value); if (msg.type === 'result') renderResult(msg.data); }); // SW 侧：接收并转发给 offscreen chrome.runtime.onConnect.addListener((port) => { if (port.name !== 'inference') return; port.onMessage.addListener(async (msg) => { if (msg.type === 'infer') { const result = await forwardToOffscreen(msg.text, (p) => { port.postMessage({ type: 'progress', value: p }); }); port.postMessage({ type: 'result', data: result }); } }); });2.2 消息丢失与重复：一个真实的数据错乱案例
讲个我踩过的坑。早期版本我用sendMessage做推理请求，结果在批量处理 50 条文本时，出现了结果和原文对不上的情况——第 3 条的结果显示成了第 7 条的。排查后发现两个问题叠加：
第一，sendMessage是异步的，我发出去 50 条消息没有等待响应就继续发，SW 侧处理顺序和发送顺序不一致。第二，SW 在处理过程中被回收了一次，部分消息丢失，而我的代码没有做超时重试，导致回调错位。
修复方案是引入请求 ID 做关联，并且改用长连接保证顺序：
// 给每个请求打上唯一 ID let seq = 0; function requestInference(text) { const id = ++seq; return new Promise((resolve, reject) => { const timer = setTimeout(() => reject(new Error('timeout')), 30000); pending.set(id, { resolve, timer }); port.postMessage({ type: 'infer', id, text }); }); } port.onMessage.addListener((msg) => { const p = pending.get(msg.id); if (!p) return; // 已超时或重复，直接丢弃 clearTimeout(p.timer); pending.delete(msg.id); p.resolve(msg.data); });注意：
pending这个 Map 如果放在 SW 的全局作用域，SW 被回收后就没了。所以要么保证 Port 连接期间 SW 不被回收（长连接本身就有这个效果），要么把 pending 状态也持久化。我选择前者，因为长连接已经解决了存活问题。
2.3 offscreen document 的创建时机与单例管理
offscreen document 有个坑：chrome.offscreen.createDocument在已经存在时会抛错。而 SW 被回收重启后，你可能不知道 offscreen 是否还活着。所以创建前必须先检查：
async function ensureOffscreen() { const existing = await chrome.runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] }); if (existing.length > 0) return; await chrome.offscreen.createDocument({ url: 'offscreen.html', reasons: ['WORKERS'], justification: 'Run on-device AI inference' }); }chrome.runtime.getContexts是较新的 API，比早期用clients.matchAll判断要可靠得多。reasons字段必须从官方枚举里选，跑 AI 推理用WORKERS或BLOBS都行，但 justification 要写清楚，审核时会看。
这里还有个实战经验：offscreen document 不要频繁创建销毁，因为每次创建都要重新加载 WASM 和模型，开销很大。我的做法是首次创建后一直保留，直到浏览器关闭。如果担心内存占用，可以在闲置超过一定时间后主动closeDocument，但要配合一个"下次需要时重建"的逻辑。
3. 端侧 AI 落地：模型怎么塞进插件、推理怎么跑得动
把 AI 推理放到端侧，动机很实际：用户数据不出本地、没有网络延迟、不依赖后端成本。但浏览器环境对端侧 AI 并不友好——内存受限、没有 GPU 直通（WebGPU 还在普及中）、扩展还有 CSP 和包体积限制。这一节讲我实际跑通的方案。
3.1 模型选型与量化：为什么我最终选了 ONNX Runtime Web
端侧 AI 在浏览器里的推理后端主要有几个选择：TensorFlow.js、ONNX Runtime Web、WebLLM（基于 WebGPU 跑大模型）。我做的任务是文本分类和轻量语义匹配，不是生成式大模型，所以 WebLLM 那种动辄几百 MB 的方案直接排除。
选型对比我整理成表：
| 方案 | 适用场景 | 包体积 | 我的评估 |
|---|---|---|---|
| TensorFlow.js | 通用，生态好 | 中等 | API 友好，但算子覆盖不如 ONNX 全 |
| ONNX Runtime Web | 跨框架模型，算子全 | 中等 | 最终选择，模型转换链路成熟 |
| WebLLM | 生成式大模型 | 极大 | 不适合轻量任务，且强依赖 WebGPU |
| Transformers.js | HuggingFace 模型直用 | 中等 | 底层也是 ONNX，封装更厚 |
最终选 ONNX Runtime Web 的核心理由是：我的模型是从 PyTorch 导出的，转 ONNX 最顺，而且 ORT 的 WASM 后端在 CPU 上跑小模型完全够用。模型本身做了 INT8 量化，原始 FP32 模型 45MB，量化后压到 12MB，精度损失在可接受范围内（分类准确率从 94.2% 掉到 93.5%）。
量化这一步很关键，直接决定插件包体积能不能接受。Chrome 应用商店对包体积没有硬性上限，但超过几十 MB 用户下载体验会很差。我的做法是把模型文件单独放在web_accessible_resources里，首次使用时才加载，而不是打包进主 bundle。
3.2 在 offscreen 里跑推理的完整链路
为什么推理要放 offscreen 而不是 SW？三个原因：SW 没有 DOM，很多推理库初始化依赖 DOM 或document；SW 会被回收，推理跑到一半被中断是灾难；offscreen 可以创建 Web Worker，把推理放到 worker 里避免阻塞。
完整链路是这样的：
// offscreen.js import * as ort from './ort.min.js'; let session = null; async function initModel() { ort.env.wasm.wasmPaths = chrome.runtime.getURL('wasm/'); session = await ort.InferenceSession.create( chrome.runtime.getURL('models/classifier_int8.onnx'), { executionProviders: ['wasm'], graphOptimizationLevel: 'all' } ); } async function runInference(inputIds, attentionMask) { if (!session) await initModel(); const feeds = { input_ids: new ort.Tensor('int64', BigInt64Array.from(inputIds), [1, inputIds.length]), attention_mask: new ort.Tensor('int64', BigInt64Array.from(attentionMask), [1, attentionMask.length]) }; const output = await session.run(feeds); return output.logits.data; } // 接收 SW 的消息 chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => { if (msg.target !== 'offscreen') return; runInference(msg.inputIds, msg.attentionMask) .then((data) => sendResponse({ ok: true, data })) .catch((err) => sendResponse({ ok: false, error: err.message })); return true; // 保持消息通道开放以支持异步响应 });这里有个必须注意的点：onMessage里如果要异步sendResponse，必须return true，否则消息通道会提前关闭，响应发不回去。这个坑我在 SW 和 offscreen 之间来回调试了无数次才记住。
分词（tokenization）这块也要在端侧做。我用的是一个精简版 BPE 分词器，词表打包成 JSON，加载后常驻内存。分词本身很快，瓶颈主要在模型推理。实测下来，单条 128 token 的文本，INT8 量化模型在普通笔记本上推理耗时约 40-80ms，完全能满足交互需求。
3.3 性能与内存：那些让插件卡死的细节
端侧 AI 最怕的就是把浏览器拖卡。我踩过的几个典型问题：
内存泄漏：ORT 的 Tensor 对象如果不释放，多次推理后内存会持续上涨。虽然 JS 有 GC，但 WASM 堆内存需要显式管理。我的做法是复用输入 Tensor 的缓冲区，避免每次推理都新建大数组。
首次加载卡顿：模型首次加载要读 12MB 文件并初始化 WASM，大概需要 1-2 秒。如果放在用户点击的同步流程里，会明显卡顿。我的方案是插件安装后就在后台预热，用户真正用时模型已经就绪。
并发推理：如果同时来多个推理请求，WASM 后端是单线程的，会排队。我加了一个简单的请求队列，超过阈值的请求直接返回"繁忙"提示，避免堆积。
// 简单的推理队列 const queue = []; let running = false; async function enqueue(task) { return new Promise((resolve, reject) => { queue.push({ task, resolve, reject }); drain(); }); } async function drain() { if (running || queue.length === 0) return; running = true; const { task, resolve, reject } = queue.shift(); try { resolve(await task()); } catch (e) { reject(e); } finally { running = false; drain(); } }提示：WASM 后端的线程数可以通过
ort.env.wasm.numThreads配置，但多线程需要 SharedArrayBuffer，而 SharedArrayBuffer 又要求页面处于跨源隔离状态。扩展页面默认不满足这个条件，所以实际能用的还是单线程。别在这上面浪费时间。
4. 工程化收尾：调试、打包与上线后的那些事
功能跑通只是开始，真正让插件能稳定交付的是工程化环节。MV3 的调试体验比 MV2 差不少，尤其是 SW 的调试，很多人不知道怎么下手。
4.1 Service Worker 的调试入口与日志技巧
SW 的 console 不在普通 DevTools 里，需要单独打开：在chrome://extensions找到你的插件，点击 "Service Worker" 那一行的链接，会弹出一个独立的 DevTools 窗口。这个窗口关掉后 SW 的日志就看不到了，所以调试期间别关。
更麻烦的是 SW 被回收后，之前打的日志全没了。我的做法是在关键路径上把日志同时写进chrome.storage.session，这样即使 SW 重启也能回溯。另外chrome.runtime.onInstalled和onStartup事件可以用来标记 SW 的生命周期，方便判断是不是被回收重启了。
chrome.runtime.onStartup.addListener(() => { console.log('[SW] browser startup, SW fresh'); }); // 在 SW 顶部打一个标记，每次重启都会执行 console.log('[SW] alive at', Date.now());如果这个 "alive" 日志频繁出现，说明 SW 在被反复回收，得检查是不是有长任务没拆好。
4.2 打包体积控制与按需加载
插件包体积直接影响审核和用户体验。我的控制策略：
- 模型文件、WASM 文件不打包进主 bundle，放
web_accessible_resources按需加载。 - 用构建工具（我用的 esbuild）做 tree-shaking，把没用到的 ORT 算子剔除。
- 分词器词表做压缩，JSON 换成二进制格式能省一半体积。
实测下来，主 bundle 控制在 200KB 以内，模型和 WASM 加起来约 15MB，整体在可接受范围。如果模型再大，就得考虑分片加载或者放到后端了——但那就违背端侧 AI 的初衷了。
4.3 上线后遇到的真实问题与修复
上线后收到几类反馈，都是测试阶段没覆盖到的：
低配设备上推理超时：老机器上单次推理超过 200ms，用户感知明显。修复是加了设备能力探测，低配设备自动降级到更小的模型或者直接走规则匹配。
多标签页并发：用户同时开多个标签页，每个页面的 content script 都发推理请求，offscreen 队列被打满。修复是加了全局并发限制，超出部分排队并给用户反馈。
SW 与 offscreen 状态不同步：SW 重启后不知道 offscreen 里的模型是否已加载，重复初始化。修复是用getContexts检查 offscreen 存在性，并通过消息确认模型状态。
这些问题没有一个是文档里会写的，全是实际跑起来才暴露的。我的体会是，MV3 插件的复杂度已经从"写脚本"上升到了"设计一个分布式小系统"，进程间的状态一致性、生命周期管理、资源调度，这些后端工程里的老问题，现在前端插件开发者也得面对了。
如果你正准备从 MV2 迁移或者新做一个带 AI 能力的插件，我的建议是先把 Service Worker 的生命周期模型吃透，再动手写业务逻辑。通信层一定要用长连接加请求 ID，别图省事用 sendMessage 裸奔。端侧 AI 这块，模型量化和 offscreen 隔离是两条必须走的路，绕不过去。至于调试，早点习惯那个独立的 SW DevTools 窗口，它会成为你最常待的地方。
