入行这么多年我经常见到有人把浏览器插件想成一个小脚本改改页面样式、往页面里塞一段逻辑完事。可当你真把一个插件从 MVP 推到线上被用户报了一堆跨标签页不同步、后台任务被回收、敏感数据泄漏的问题之后会明白一件事——这玩意早就是个正经的工程了。尤其是 Manifest V3MV3全面铺开之后很多以前“把代码塞进 background 常驻就行”的玩法彻底失效。现在做一个能扛住真实用户场景的浏览器插件至少得面对三件事MV3 的事件驱动架构、多上下文之间的跨进程通信、以及把越来越重的 AI 能力塞进浏览器里跑。如果再算上 TypeScript、Vite、自动化构建、权限收敛这些工程化要求它已经完全超出了“小脚本”的范畴。这篇文章我打算从这三个维度做一次完整复盘。我会把 MV3 的架构变化、跨进程通信的几种姿势、端侧 AI 的落地路径讲透再给出一套可以直接抄的工程化骨架。适合正在从 MV2 迁到 MV3 的开发者、准备做商业插件但还停留在单文件脚本阶段的朋友也适合那些想在插件里接本地 AI 模型、又不知道怎么绕过 Service Worker 限制的人。1. 内容整体设计与思路拆解1.1 为什么现代插件不能被叫做“小脚本”先聊个现象。很多教程喜欢用“用户脚本”或“书签小工具”来引入插件开发这在十年前没错那时候一个后台页面能把所有状态都在内存里放着content script 随手往页面里塞个 script 标签也能执行外部代码开发体验和写一个带生命周期回调的 Node 服务差不多。但现在的插件要处理的问题复杂太多了。一个像样的翻译插件要从 popup 拿设置、往当前页面的 content script 发指令、把翻译请求送到后台去做网络请求、再把结果写回页面高亮。一个稍大的效率插件可能要监听多标签页的导航事件、维护跨标签页的队列状态、在用户关掉浏览器后继续执行定时任务。这些需求叠在一起插件内部天然就是一个多进程应用——就算不考虑浏览器强制隔离你也得主动拆模块不然代码根本维护不下去。所以 MV3 不是浏览器厂商突然脑袋一热搞出来的新规范而是整个插件生态演进后的必然结果。它用“事件驱动”取代“常驻后台”用“本地代码优先”挤掉远程脚本用“声明式规则”替换高危的网络请求拦截。这些变化一开始让人很痛苦但设计思路其实是健康的让插件更靠近一个标准 Web 应用而不是一个拥有系统级权限的野孩子。如果你还抱着“插件的本质就是往页面里注入一段 JS”的心态后面所有东西都会别扭。心态先转过来插件是一个有独立生命周期的应用页面只是它需要交互的外部世界。1.2 MV3 带来的架构革命MV3 最核心的变化有三个每一个都直接影响架构设计。第一后台脚本变成了 Service Worker。在 MV2 里背景页是一个真正的 HTML 页面可以常驻内存放全局变量、开长连接、保持状态都没问题。MV3 的 background 是一个只存活在事件周期里的 Service Worker它不保证常驻空闲大概 30 秒左右就可能被浏览器销毁下次事件来了再重新唤醒。所有以前“放内存里就行”的状态现在要么落盘到 chrome.storage要么就只能接受每次事件循环重新拉取。第二CSP 和远程代码限制极严。MV3 不允许任何 eval、远程脚本、远程样式。以前那种“在后台动态拼接一段 JS 然后 executeScript 塞进页面”的操作直接被封死。所有注入页面的 JS 文件必须先放进插件的 web_accessible_resources并且是本地静态文件。这导致很多“动态生成脚本逻辑”的架构被迫重构。第三网络请求拦截从 webRequest 的阻塞模式换成了 declarativeNetRequest。MV3 里除非特殊情况不能再用 JavaScript 同步改变请求响应只能用浏览器预编译的规则去过滤、重定向、修改请求头。规则条数有上限规则匹配优先级也有讲究不是所有拦截逻辑都能用几行正则搞定。这直接决定了“广告拦截类”“抓包类”插件的实现方式。这些变化叠加在一起就是在逼你进行模块化设计。Service Worker 只做事件入口和轻量调度content script 负责与页面 DOM 交互popup 和 options 页面负责 UI而所有跨模块状态用统一的存储和消息机制来传递。后面我讲的分层架构就是从这种约束里长出来的。1.3 拆解后的分层设计我一般把现代插件拆成五层和常规后端的分层很像表现层popup、options、side panel以及 content script 内部渲染出来的 UI。这层只管展示和收集用户输入不写业务逻辑。逻辑层Service Worker负责接收所有事件消息、调度任务、完成网络请求、维护全局状态。页面交互层content script与宿主页面 DOM 打交道负责提取信息、注入 UI、监听页面变化。存储层chrome.storage.local / session / sync承担状态持久化。能力层端侧 AI、OCR、剪贴板、桌面通知、native messaging 等扩展能力通常由专门的模块封装。层与层之间不直接引用全部通过消息传递。这是 MV3 下最安全的做法因为浏览器本身就把这些上下文隔离成了不同的执行环境你在 content script 里拿不到 Service Worker 的全局变量反过来也一样。这种分层看起来繁琐但好处非常明显任何一层都可以独立替换、独立测试。比如你想把端侧 AI 引擎从 Transformers.js 换成 ONNX Runtime Web只需要改能力层的实现消息协议不变上层不用动一行代码。2. 核心细节解析与实操要点2.1 MV3 的三大关键变更Service Worker 生命周期这块我多讲一点因为这是最多人踩坑的地方。MV3 的 background SW 不是常驻进程它生命周期大致是注册完成后启动接收事件执行回调然后进入空闲超时后销毁。Chrome 默认的空闲销毁时间现在大约是 30 秒但这不是一个稳定的公开 API不同版本有调整过。更麻烦的是你不能通过代码续命也不能主动阻止销毁。所以在设计后台任务时一定要默认“随时可能被杀”。全局变量只能放临时缓存不能依赖它保存关键状态。跨事件持久化用 chrome.storage.session这个存储区能保存在当前浏览器会话里存活的数据并且访问速度比 local 快非常适合做 SW 的内存替代品。第二关键点是权限模型。MV3 把权限拆成 permissions 和 host_permissions 两类要求你声明得非常精确。比如你想用 chrome.scripting.executeScript 往页面注入脚本除了要声明 scripting 权限还要在 host_permissions 里声明哪些站点允许注入或者运行时通过 activeTab 权限获取临时授权。你不能再写一个 all_urls 了事审核和用户感知都更严。第三关键点是 content_security_policy。MV3 的 CSP 默认就是 script-src self; object-src self你不能往里加远程域名。这意味着所有运行时代码都要打包进本地产物。我见过一个项目把后端模板字符串直接注入页面的MV3 之后就废了只能改成把模板 JS 文件放进 web_accessible_resources通过 script tag 或 executeScript 的文件参数加载。2.2 跨进程通信的姿势与避坑MV3 下的插件至少有四个独立的 JS 上下文Service Worker、popup/options 页面、content script、以及被注入到页面的 iframe。它们之间唯一的沟通方式就是消息传递所以理解 chrome.runtime / chrome.tabs 的 API 是刚需。最常用的三组 APIchrome.runtime.sendMessage / chrome.runtime.onMessage从任意扩展上下文向 Service Worker或其他监听者发消息。chrome.tabs.sendMessage从扩展上下文向指定标签页内的 content script 发消息。chrome.runtime.connect / Port建立长连接适合双向持续通信比如实时事件流。看起来很简单但细节坑很多。第一个坑是消息格式。Chrome 消息传递本质是 JSON 序列化不能传 DOM 节点、不能传 class 实例、不能传函数。你从 content script 里取到一个 Element想发给 Service Worker不行。你得先提取成文本、属性或 rect 坐标再通过消息传过去。第二个坑是生命周期与 sendResponse 的异步问题。在 MV3 的 Service Worker 里如果 onMessage 监听器里做了异步操作比如等待端侧 AI 推理结果你必须 return true 来保持消息通道打开否则 sendResponse 会在监听器同步执行完就被 Chrome 认为已经结束后端拿不到回调。这个细节我见过太多人丢过。第三个坑是消息发送时没有目标。chrome.runtime.sendMessage 会发给所有监听 runtime.onMessage 的上下文包括 background SW、popup、options、其他扩展页面。如果你在多个上下文里都监听了同一个消息会产生重复响应。所以我习惯把消息体里加一个 target 字段比如 { type: AI_CLASSIFY, payloadId: xxx }每个上下文先判 target 再处理避免串扰。第四个坑是报错处理。chrome.tabs.sendMessage 如果目标 content script 还没注入会抛 “Could not establish connection. Receiving end does not exist.”。这种错误必须捕获最好用 chrome.runtime.lastError 或者 Promise 的 catch 统一处理而不是任由它出现在控制台里。更稳妥的做法是先 chrome.scripting.executeScript 注入一次再发消息。跨进程通信的架构上我建议做一个统一的消息封装层把 sendMessage 包成带 Promise 的调用统一处理超时、错误、目标上下文。不要每个文件都裸调用 chrome API否则后面加一个消息字段要在全项目里搜索替换。2.3 端侧 AI 的落地思路现在前端生态里跑的端侧 AI主流路线有两条一是 Transformers.js用纯 JS/Wasm 转译 Hugging Face 的预训练模型二是 ONNX Runtime Web / WebGPU 推理。这两条路都能跑在浏览器扩展里但它们对运行环境的要求不一样不能一概而论。最重要的一点MV3 的 Service Worker 本质上是一个 Worker 线程不是所有浏览器 API 都开放给它。比如 WebGPU 在 Service Worker 里目前支持很有限OffscreenCanvas 也不是全版本都可用。所以如果你要跑图形相关的模型或者依赖 WebGPU 加速的推理直接在 background 里做大概率会翻车。我的落地策略是把端侧 AI 推理放到一个独立的 offscreen document 里或者直接放到 content script 里。offscreen document 是 Chrome 专门为 MV3 提供的隐藏文档可以创建 DOM、用 Worker、跑 WebGPU非常适合承载本地推理。它不会显示给用户但拥有完整页面能力。另一个选择是扔到 content script 里让它和页面上下文共享同一个环境好处是不用单独管理生命周期坏处是会拖慢页面渲染而且用户可能觉得插件在偷窥页面。模型加载是另一个大坑。Transformers.js 默认会去 Hugging Face Hub 下载模型这在插件里根本不可行网络受限、审核受限、用户隐私也会被质疑。正确做法是开发时把模型下载下来作为静态资源打进插件包或者首次启动时下载到 IndexedDB 并做版本缓存。插件包里有体积上限所以模型要尽量小。量化过的蒸馏模型是首选比如 distilbert-base-uncased-finetuned-sst-2-english 的量化版本大概几十 MB还能接受。超过 100 MB 就要认真考虑是不是应该换模型或者走服务端推理了。推理线程方面Transformers.js 内部会创建 Web Worker 或 Wasm 线程在 Service Worker 里跑有可能出现线程池初始化问题所以我建议尽量在 offscreen document 里做推理然后用消息把结果传回 Service Worker。这样 SW 保持轻量负责调度就行。端侧 AI 的价值在于隐私、离线、零延迟。不是所有任务都适合端侧。像文本分类、情感分析、实体抽取、图片标签、OCR 这种对延迟敏感、又涉及用户本地数据的任务非常适合端侧跑。而大语言模型那种动辄几十 GB 的目前放进插件里还不现实老实接服务端接口就好。3. 实操过程与核心环节实现3.1 搭一个 TypeScript Vite 的 MV3 工程骨架工程化不是非要上重型框架但 TypeScript Vite 的组合是目前性价比最高的方案。TypeScript 能让你在写多上下文代码时明确类型边界Vite 能快速构建多入口产物配一个热更新插件就能在开发时流畅调试。我用的是 WXT 这个框架它把 Vue/React、Vite、自动生成 manifest、自动加载扩展、跨浏览器调试都集成好了。如果你想少踩坑直接用 WXT 初始化一个模板比手搓 Vite 配置省事得多。目录结构大概是这样的my-extension/ src/ entrypoints/ background.ts content/ index.ts style.css popup/ index.html main.ts options/ index.html main.ts components/ utils/ lib/ ai/ package.json tsconfig.json wxt.config.ts入口文件按职责拆分background 只处理消息与调度content 只管页面交互popup 只管 UI。这样后续加功能或加权限改动都能控制在局部。wxt.config.ts 里可以指定 manifest 的基础配置export default defineConfig({ manifest: { name: my-extension, version: 0.1.0, manifest_version: 3, permissions: [storage, scripting, activeTab], host_permissions: [all_urls], action: { default_popup: popup/index.html, }, }, });注意不要把权限写满。开发初期可以临时用 host_permissions 的 all_urls 方便调试但发布前一定要收敛只留实际会访问的站点或页面。权限越大上架审核越难用户安装时的信任感也越差。在 WXT 里content script 可以选择在主页面注入或者在 iframe 注入。默认是注入主页面但如果你要在页面里渲染浮动 UI很容易被页面 CSS 污染。这时候可以考虑用 Shadow DOM 隔离或者干脆用 offscreen document 里开一个 iframe再通过 postMessage 通信。3.2 打通 popup 到 content script 的完整消息链路我举一个实际例子用户点击 popup 里的按钮插件需要读取当前页面上的所有商品价格并汇总再展示到 popup 上。第一步popup 点击时先拿到当前活动标签页// popup/main.ts async function collectPrices() { const [tab] await chrome.tabs.query({ active: true, currentWindow: true }); if (!tab?.id) { throw new Error(No active tab); } // 调用后台让后台处理逻辑而不是 popup 直接联系 content const result await chrome.runtime.sendMessage({ type: COLLECT_PRICES, tabId: tab.id, }); renderPriceList(result); }这里我让 popup 把 tabId 丢给后台后台再去联系 content script。为什么绕一层因为后台可以统一处理权限、错误、重试而且 popup 可能被用户随时关闭长任务交给后台更可靠。第二步background 的 Service Worker 里注册消息监听// background.ts chrome.runtime.onMessage.addListener((message, sender, sendResponse) { if (message.type COLLECT_PRICES) { handleCollectPrices(message.tabId) .then(sendResponse) .catch((err) sendResponse({ error: err.message })); return true; // 保持异步通道 } }); async function handleCollectPrices(tabId: number) { // 先确保 content script 已注入 try { await chrome.tabs.sendMessage(tabId, { type: PING }); } catch { await chrome.scripting.executeScript({ target: { tabId }, files: [content-scripts/content.js], }); } // 再向 content script 正式要数据 const response await chrome.tabs.sendMessage(tabId, { type: EXTRACT_PRICES }); return response; }第三步content script 监听消息并返回页面数据// content/index.ts chrome.runtime.onMessage.addListener((message, _sender, sendResponse) { if (message.type PING) { sendResponse({ ok: true }); return false; } if (message.type EXTRACT_PRICES) { const items Array.from(document.querySelectorAll(.product-price)) .map((el) el.textContent?.trim()) .filter(Boolean); sendResponse({ count: items.length, items }); return false; } });这套链路虽然绕但每一层职责很清楚出现问题也能快速定位。如果以后想给 content script 增加更多功能只需要在 background 的路由里增加新的消息类型不用动 popup。还有一点值得注意消息体里的 type 命名最好统一前缀比如用插件名缩写作为开头。这样就算和其他扩展的 content script 消息混在一起也不会冲突。3.3 在插件里跑一个端侧 AI 模型我拿文本情感分析举例这是端侧 AI 最容易理解和验证的场景。安装 Transformers.jsnpm install huggingface/transformers然后在能力层封装一个推理模块我用 offscreen document 思路// lib/ai/sentiment.ts import { pipeline } from huggingface/transformers; let classifier: any null; export async function classifySentiment(text: string) { if (!classifier) { // 这里用本地模型路径而不是从远端拉取 classifier await pipeline(sentiment-analysis, /models/distilbert-sst2-quantized); } const result await classifier(text); return result; }为了让 offscreen document 能加载本地模型需要把模型文件放到 public 目录或者通过 Vite 的 static 资源处理。WXT 里可以把模型放在 public/models 下构建时会被原样拷贝到产物。调用侧在你的 background 里收到 AI 请求后先创建 offscreen document如果还没创建再向它发消息// background.ts let offscreenReady false; async function ensureOffscreenDocument() { if (offscreenReady) return; await chrome.offscreen.createDocument({ url: offscreen/ai.html, reasons: [DOM_PARSER], justification: Run on-device AI inference, }); offscreenReady true; } chrome.runtime.onMessage.addListener((message, _sender, sendResponse) { if (message.type AI_SENTIMENT) { ensureOffscreenDocument() .then(() { // 通过 runtime.sendMessage 转发给 offscreen document return chrome.runtime.sendMessage({ type: AI_SENTIMENT_EXEC, payload: message.payload, }); }) .then(sendResponse) .catch((err) sendResponse({ error: err.message })); return true; } });offscreen document 里的监听器负责真正执行推理// offscreen/ai.ts import { classifySentiment } from ../lib/ai/sentiment; chrome.runtime.onMessage.addListener(async (message, _sender, sendResponse) { if (message.type AI_SENTIMENT_EXEC) { const result await classifySentiment(message.payload); sendResponse({ label: result[0].label, score: result[0].score }); return true; } });这个方案的好处是Service Worker 只负责调度重量级推理在 offscreen document 里不会因为 SW 空闲被销毁导致推理中断。模型也只加载一次后续调用复用内存里的实例速度会快很多。如果模型文件实在太大可以先放在远程 CDN首次运行时下载到 IndexedDB 并校验哈希后续直接从本地加载。但插件上架审核时下载外部文件属于高风险行为最好不要放在正式版里。3.4 构建发布前必须做的几件事工程化不只是代码结构还包括发布流程。代码检查要跑起来ESLint Prettier 是标配。我强烈建议在 package.json 里加上 lint-staged husky在 commit 前自动校验不然团队协作时风格立刻就会乱。类型检查也要进 CI。TypeScript 的严格模式不要关特别是跨上下文通信的 payload 类型最好用 zod 或 yup 在运行时校验一次。端到端类型 运行时校验双保险能挡住大部分诡异 bug。自动化打包也建议做。WXT 提供了 build 命令能一次性产出 Chrome、Firefox、Edge 的产物。如果想在 CI 里自动打 zip就再加一步用 GitHub Actions 或者 GitLab CI 把产物压缩并上传到 release。源码调试时我习惯用 web-ext 跑 Firefox 的自动加载Chrome 用 WXT 自带的热更新能大幅减少手动 reload 操作。发布前还要做一遍权限审计把 manifest.json 里所有权限列出来逐个确认是否真的在用。没用到的权限全部删掉。插件被浏览器标记为“有毒”或审核被拒很多时候就是因为权限声明过于夸张。4. 常见问题与排查技巧实录4.1 MV3 适配期的顽固报错清单Service Worker 被频繁销毁但内存里还有任务在执行。这个问题根源就是上面讲的生命周期。解决思路是把任务拆小尽量不依赖 SW 持续运行。如果真需要长时间任务比如文件扫描把进度写到 chrome.storage.session每次事件唤起时从上次进度开始而不是从头再来。我踩过一次坑用户导出一个两万条记录的 CSVSW 在导出中途被销毁重新唤起后状态丢了数据全乱。后来改用“任务分片 断点续跑”问题才解决。还有一类问题是消息发送时前面找不到接收端。常见场景是插件刚安装完用户立刻点 popup此时 content script 还没注入。你可以先发一个 PING 探测失败再注入这是最保险的顺序。不要假设 content script 一定已经存在。CSP 报错也是高频问题。遇到Refused to execute inline script时先检查是不是在 HTML 里写了内联脚本或者动态创建了 script 元素。MV3 下所有 JS 必须放到独立文件里至少要在 build 阶段单独输出。再有一个隐蔽问题在 Firefox 里background 的 Service Worker 支持情况和 Chrome 并不完全一致。有些 MV3 API 在 Firefox 117 之前根本没实现。所以跨浏览器测试不能省尤其要关注 browser 对象和 code 的兼容差异。手里备一份 web-ext 实时调试工具能省很多事。4.2 端侧 AI 的现场踩坑模型加载慢是第一个坑。本地模型不必每次从磁盘都重新反序列化Transformers.js 内部已经有缓存但首次加载一个几十 MB 的模型在低端设备上会卡好几秒。体验上必须给用户一个加载状态不能干看着白屏。我见过一个项目推理按钮点了之后什么都没有用户以为插件坏了其实是模型还在加载。加一个 loading 指示器至少能降低投诉率。第二个坑是内存。浏览器插件本身占用的内存就不小再加载一个 AI 模型很可能让低配电脑崩溃。解决办法是尽量用量化模型并且在推理结束后主动释放不需要的缓存。Transformers.js 支持使用环境变量调整设备类型比如用 wasm 而不是 webgpu减少显存占用。实测下来量化模型 CPU 推理虽然慢一点但稳定性好很多。第三个坑是消息序列化。推理结果如果是嵌套对象里面可能含有 BigInt 或 Uint8Array直接塞进 message 会丢失。我需要统一转成 JSON 安全的格式比如把向量转成普通数组把概率转成字符串再传递。第四个坑是模型的离线可用性。开发时我用远程 URL 加载模型方便调试但发布前一定要把模型固定到本地目录否则用户没网就完全不可用。如果模型需要更新就更新插件版本不要走“动态拉取模型”这条路审核会出问题用户隐私也会受影响。4.3 工程化与跨浏览器兼容WXT 虽然减少了跨浏览器差异但有一个老问题Firefox 的 MV3 background 实现仍不稳定。在 Firefox 里用 chrome.* 和 browser.* 两套 API 都有但行为略有差异。我最后的做法是把所有 API 调用封装进一个 bridge 层统一用 chrome.* 写构建时用 webextension-polyfill 做 shim这样 Firefox 下也能跑。版本管理上推荐语义化版本。插件上架后用户无法像普通 Web 应用那样自动更新到最新版所以每次发布前都要准备好 CHANGELOG明确说明哪个行为变化了。如果做的是企业级插件最好提供旧版本的回滚方案防止线上故障导致全员无法使用。最后是测试。插件的 UI 部分可以用 Storybook 单独开发消息链路用 msw 或 mock chrome API 做单元测试端到端测试用 Playwright 加扩展模式跑能覆盖大部分核心路径。我见过很多团队把时间花在手动点页面上一旦插件规模变大回归测试根本做不完。至少把消息协议层测一遍你会发现很多问题根本不会等到用户报出来。最后聊点个人体会做浏览器插件这行最容易低估的就是“上下文隔离”带来的复杂度。很多人写完 content script 就觉得大功告成但真正能撑起一个商业级插件的恰恰是那套看不见的消息链路和生命周期管理。MV3 的推进让这一切变得强制化短期看是折腾长期看是在逼我们把代码写得像正经软件而不是一次性脚本。我自己做完这个项目后最大的变化是写任何功能前先画一遍“消息从哪里来到哪里去中间经过谁”再动手写代码。哪怕是一个最简单的浮层按钮也先想清楚它的状态存在哪里、谁负责更新、出错了怎么办。这套方法论放在任何复杂前端项目里都通用。如果这篇文章能帮你少踩几个坑或者让你重新审视手头插件的架构那我的复盘就没白写。下一次项目遇到“是否要在插件里做端侧 AI”的问题时希望你能想起我说的那句话不是所有模型都适合塞进浏览器但真正适合的端侧跑起来是真的香。