在建立浏览器侧边栏 AI 助手的过程中，我遇到了不少“看似简单却让人抓狂”的坑。下面把这些经验整理成可复用的知识点，方便你定位并解决类似问题。

开场

前几个月我实现了一个基于 MV3 的 Chrome 插件——浏览器侧边栏 AI 助手。它可以在任何页面弹出对话框、划词翻译、全文等功能。插件主要思路是：content‑script 把页面信息发给 background。background 再通过 WebSocket 与本地 Agent Server 通信，最终调用 DeepSeek API 获取答案。

这篇文章不提供完整代码，而是聚焦踩过的实际坑现象、排查过程、根因与方法。

从前置知识来看，Chrome 的三大角色

结构概览

• manifest.json: 声明权限、角色与入口文件。
• content‑script: 运行在网页内。负责 DOM 操作和事件监听。
• background : 后台逻辑，独立于任何网页。老实说，负责消息转发、存储还有与外部服务器通信。
• sidepanel: Chrome 的侧边栏 UI，用来展示聊天界面。

隔离世界 VS 主世界

• isolated world: 默认模式，content‑script 与页面 JS 在各自沙箱中互不干扰。能安全访问 chrome.*,但无法访问页面全局变量。
• Main world: 配置 "world":"MAIN"。内容脚本与页面共享同一全局作用域，可直接访问 window.xxx,也会被页面脚本修改或删除。

消息传递机制

.sendMessage/.onMessage.addListener

User Gesture 约束说明：

某些 API 如 只能在使用者手势同步调用链里使用；异步等待会导致浏览器拒绝执行。

User Pain Point：

• “侧边栏永远不弹”——因为未满足使用者手势条件而被拦截。说起来，”

PITFALL #1：掘金网站导致 content‑script 崩溃

现象 — 划词工具条在掘金完全失效，无报错！

排查过程的观点是，

全局错误捕获报错： TypeError: Cannot read properties of undefined at index.js::…提示内容脚本被提前终止，

根因这方面。

我把 content‑script 设置为 "world":"MAIN",与页面共享同一 window 对象。掘金主动删除了 ,所以在脚本里执行 alert。抛出 TypeError 并停止后续代码。 说起来，普通站点未删 chrome 对象，故正常工作。

方法的观点是，

• `world` 字段省略即可默认回到 isolated world；显式写为 “ISOLATED” 更易维护。

{ "content_scripts":,"js":,"run_at": "document_idle"。"world": "ISOLATED" } ] }

User Pain Point — “为什么之前没有报错？为什么普通站点 OK，”

• 因为掘金清理了 `window.chrome`；话说回来，Chrome 新版已将其设为只读属性。但旧版仍可被删除，导致错误隐藏更明显。

---

PITFALL #2：sidePanel.open 必须在使用者手势里调用导致侧边栏打不开

现象 — 点击“翻译”后报错：“sidePanel.open may only be called in response to a user gesture.”

从根因分析来看，

• `runtime.sendMessage` 是异步；中间经过 await storage 后原始点击上下文已丢失 → 浏览器认为不是同步手势链，所以拒绝 open 调用。

---

PITFALL #3：Shadow DOM 中 `contains` 的误判导致按钮无反应

现象 — 工具条内部按钮第一次点击完全无效

---

PITFALL #4：SSE 流式输出引发架构拆分危机

• SSE: 单向推送协议，用于实现“打字机效果”。SSE 能让 AI 模型逐 token 推送数据，而非一次性返回完整文本。

Avoiding Architecture Split:


我们把流式接口的返回结构设计为与非流式一致，只差一个可选回调函数 ;

– 即使开启流式，也能直接调用相同逻辑处理响应。

– 前端渲染层也只需改成增量 append + 最终覆盖即可，无需拆分两套业务流程。

  ，.



​

。

---