把一个带 AI 助手的浏览器扩展从“本地能跑”推到“真正能对外用”中间会坏掉一批东西而且坏的往往不是 AI 模型本身而是浏览器扩展的权限、通信、状态和发布流程。这个主题特别适合两类人一类是正在给已有扩展接 AI 能力的开发者另一类是准备从零做 AI 浏览器插件的独立开发者。下面我会按实际开发顺序把容易坏的地方、为什么会坏、怎么排查一起拆开讲。1. 先拆清楚AI 助手到底在扩展里承担什么角色1.1 角色定位决定权限、通信和 UI 方案AI 助手在扩展里不是同一个东西。常见形态有这么几种侧边栏对话助手用户随时点开一个面板跟 AI 连续聊天。页面摘要工具读取当前页面正文生成摘要或提炼重点。写作辅助在输入框、编辑器里生成或改写文本。智能推荐根据页面上下文推荐相关内容。自动化操作解析用户指令代替用户点击、填写表单、抓取页面数据。这几种形态看起来都叫 AI 助手实际架构差别非常大。最典型的影响落在三处权限、通信、UI 挂载方式。页面摘要必须读取当前网页内容意味着 content script 要能访问页面 DOM而且可能需要申请all_urls或者针对具体域名的读取权限。写作辅助要注入到输入框里对页面结构要求更高一旦网站改版注入点可能就失效了。自动化操作最麻烦既要读取页面又要模拟点击和填写审核时风险最高。侧边栏对话相对干净但会话状态、消息推送、流式输出在哪一层做又会影响后面的方案。很多项目一开始只想做一个“侧边栏聊天”后来为了读取选中文本又加了选中权限后来又为了“总结当前页面”把权限放大到所有网站。权限每放大一次容易坏的地方就多一批。与其先堆功能不如先确定角色边界。1.2 角色不清会导致返工和权限膨胀实际开发里最多的困难不是功能实现不了而是需求角色一直在变。比如用户说“我想要一个 AI 助手”但真正要的是划词后弹出一个解释按钮结果团队按聊天机器人做了最后要改造成内容脚本注入。两者架构差别很大聊天机器人重点在数据同步和流式输出划词解释重点在 DOM 注入和右键菜单注册。返工成本主要在权限设置、消息通信和 UI 挂载方式上。我建议第一步把角色画成一张图只需要四个问题用户在哪个入口触发助手AI 能看到什么输入是当前页面的正文、选中文本还是只有用户输入的文字AI 返回什么结果是一段文字、一个摘要还是一条结构化 JSON结果显示在哪里是弹窗、侧边栏还是页面内注入的面板这四个问题定下来后面所有坑都能提前排掉一部分。尤其是“AI 能看到什么输入”这一项直接决定你要不要申请读取所有网站数据的权限也决定隐私政策里怎么写。2. 最容易坏的第一层权限和 CSP 约束2.1 为什么请求会被“悄悄拦掉”浏览器扩展请求被拦截最典型的原因有三个content script 直接发 AI API 请求被页面的 CORS 策略拦掉。manifest 里的 host_permissions 没有包含目标 API 域名。扩展自身的 CSP 不允许某个第三方 SDK 加载远程脚本或执行动态代码。第一个问题最容易被忽略。content script 的 fetch 默认上下文和页面混在一起不一定能直接访问第三方 AI 服务。要跨域发请求应该放到 background service worker 里发service worker 的请求上下文是扩展自己的只要你声明了 host_permissions 就可以。这个顺序要记清楚content script 把消息发给 backgroundbackground 去发请求再把结果返回给页面。如果请求发出去没有任何响应先打开 chrome://extensions 页面找到你的扩展查看 Service Worker 的控制台日志。很多时候报错信息已经写得很明确比如“permission”或者“host_permissions”字样这时候不要先去怀疑 AI API 的 key。2.2 MV3 的 background 会休眠别把状态放在内存里Manifest V3 里background 变成了 service worker会在空闲时休眠。这意味着三件容易被忽略的事不能在 background 里长期保存对话上下文。内存一旦释放数据就丢了。不能用 WebSocket 一直保持一个长连接service worker 休眠后连接会被断开。长时间流式响应中间如果 service worker 被回收连接也跟着断。解决思路是必要数据写入 chrome.storage.session请求尽量采用短连接方式AI 流式接口用 fetch 配合 ReadableStream 在后台接收不要依赖长连接。会话状态最好由后端保存扩展只传递一个 sessionId前端永远不持有完整上下文。如果你的扩展还在用 MV2暂时没有这个问题但新提交的扩展基本上都会要求 MV3所以尽早按 MV3 的方式做规划更稳妥。2.3 CSP 和第三方 SDK 的冲突浏览器扩展默认有较强的 CSP不允许加载远程脚本也不允许执行 eval。很多 AI SDK 为了体积和兼容性可能会生成一段动态代码或者依赖内联脚本放进扩展里直接报错。遇到这种情况先别动 CSP 配置。把安全策略关掉来兼容 SDK短期看起来能跑后面审核和安全性都会出问题。更常见的做法是换一个更轻量的 SDK或者直接用原生 fetch 调 API。对扩展来说一个请求函数通常比整个 SDK 更容易受控也更容易排查问题。2.4 实际排查顺序如果页面请求一直失败我按这个顺序查确认请求是哪个上下文发出的content script、popup还是 background。打开扩展的 Service Worker 控制台看错误日志。检查 manifest 里的 permissions 和 host_permissions 有没有覆盖目标 API 域名。在 background 里单独发一次 fetch 测试目标 API。确认目标 API 的 CORS 头是否允许浏览器端访问。这里最容易踩的坑就是一看到报错就怀疑 AI API 的 key 不对、参数不对实际上 manifest 里根本没加 API 域名权限。一次请求从页面到后台再发出跨了三层每一层都可能断不能只盯最后一步。3. AI 服务接入的坑密钥、请求、流式和限流3.1 API 密钥不要放进前端至少过一层后端很多人会图省事把自己的 AI API 密钥直接写进扩展代码里。这是个大坑。浏览器扩展包是可以被解包的即使发布到商店别人也能下载到本地查看代码。密钥一旦曝光可能被别人拿去反复调用最终账单记在开发者头上。不要这么干。至少要做到密钥只放在自己的后端服务里。扩展请求自己的后端接口由后端调用 AI 服务。后端做限流和审计记录每次调用来自哪个用户、消耗了多少 token。如果只是个人小工具、暂时不想建后端也要使用云函数、边缘函数这类方式生成短期令牌。有些 AI 服务支持“用户自己填写 API Key”的模式扩展里做一个设置页让用户输入自己的 Key。这个模式代码上不复杂但要注意几点Key 建议存储在 chrome.storage.local并明确提示用户风险设置页要提供连通性测试授权码输错、Key 过期、额度不足都要有对应提示。很多服务在激活或授权时要求用户输入两步验证应用里的验证码才能完成认证。这种流程如果放在 popup 弹窗里用户焦点稍微一变弹窗就关了体验会很差。更稳的做法是放到独立标签页或侧边栏里完成授权授权完成后再把状态同步回扩展。3.2 流式响应在扩展里更容易断AI 对话通常希望实现打字机效果所以会使用流式输出。但扩展环境里流式响应有几个不稳定点popup 不能长期打开popup 失焦就关闭请求随之断掉。content script 做流式渲染页面 DOM 如果被网站框架更新渲染目标可能丢失。background 做流式转发service worker 可能休眠。用户切换标签页内容脚本如果被浏览器回收UI 状态会丢。我的建议是把流式渲染放在侧边栏或独立页面不要放在 popup 里。background 只负责发请求和转发流不持有过长生命周期。完整会话写入存储或后端流中断后可以选择继续而不是从头再来。给流式请求设置超时和断线重试策略。有一个很常见的现象用户在侧边栏里把问题问完AI 刚开始回复用户点了一下网页背景区域侧边栏如果跟随某些页面事件关闭了回复就消失了。这不算模型问题是 UI 生命周期没管好。3.3 限流、超时和成本怎么判断接入 AI API 后不能只看单次能不能返回还要关心几个指标单次请求耗时。慢接口可能超过扩展消息等待的超时时间。并发上限。用户开多个标签页同时用容易触发限流。单次调用成本。如果每次都把整页正文发给模型token 会涨得很快。失败重试。模型接口返回 429、超时或 5xx 时你的重试策略是什么。如果直接在浏览器端调第三方 AI API还要注意浏览器并发连接限制和跨域问题。更稳的方案是把 AI 调用放后端前端只做输入输出。这样密钥不暴露、限流也更容易控制出问题时可以看后端日志而不是猜浏览器行为。3.4 建议的请求链路推荐一个通用请求链路content script / 侧边栏 UI - chrome.runtime.sendMessage - background service worker - 自己的后端代理接口 - AI 服务 API - 后端透传流式响应 - background - UI为什么要加一层后端因为 API 密钥需要保护令牌签发、限流、成本统计、会话持久化都需要一个稳定的服务端位置。扩展本身不是一个适合保存秘密和大量状态的地方。几个常见参数需要提前定义好参数建议取值说明timeout30 秒以上AI 流式接口首次返回可能较慢max_tokens / max_output_tokens按产品需求控制输出长度避免无限 tokenstreamtrue对话场景建议开启流式temperature0.2 到 0.8控制随机性摘要场景可以低一些retry0 到 2 次429 和超时可以做一次重试sessionId后端生成用来保存会话状态扩展不存全部历史不要一上来就开高并发。先用一个用户、一个请求把链路跑通再慢慢加并发。并发一高限流、超时、内存占用、成本问题会同时冒出来那时候再排查就很乱。4. 页面、弹窗、侧边栏之间怎么保持状态一致4.1 状态丢失和“刚说完就忘了”AI 助手最常见的用户投诉是“我上一句它还记得怎么切了个页面就忘了”。原因通常是对话上下文存在了 popup 或 content script 的 JS 变量里页面一刷新就没了。更稳的做法会话历史写入 chrome.storage.local 或 IndexedDB。标签页切换时用 chrome.tabs 获取当前页面信息按域名或页面 URL 区分会话。跨标签同步使用 chrome.storage.onChanged 监听变化。需要更大容量时用 IndexedDB而不是把所有内容塞进 storage。chrome.storage 默认有配额限制。如果聊天记录很多很快会触顶。长期会话建议后端存储扩展只保留最近 N 条。这样既能保证 UI 快速打开也能避免存储配额报错。4.2 多标签页并发冲突用户多个标签页同时打开同一个扩展可能出现三类问题UI 组件被重复注入页面上出现两个悬浮球。两个页面同时发请求后返回的结果覆盖先返回的结果。页面 A 的摘要跑到了页面 B 的面板上。原因是 content script 是每个标签页独立注入的它们之间没有共享状态跟 background 之间的消息也容易混乱。解决办法是给每个请求加唯一标识每个标签页生成独立 id。消息里带上 tabId、pageUrl、requestId。background 转发时按 requestId 匹配返回结果。UI 注入时先检查节点是否已存在避免重复。全局操作加锁比如“一键摘要”同时只能有一个任务在跑。这部分如果没做好用户开着多个页面时扩展看起来就像是“随机坏掉”。4.3 动态页面和 SPA 路由会把 UI 冲掉很多 AI 助手会往页面里注入悬浮球或按钮结果网站是 React、Vue 这类单页应用路由切换时 DOM 被整个替换注入的节点就消失了。这不是扩展坏了而是页面框架更新了。处理方式用 MutationObserver 监听页面根节点变化必要时重新注入。不要把重要状态只存在注入节点上页面刷新后要能从存储或后端恢复。支持用户手动重新呼出面板。我的经验是不要把所有功能都依赖 DOM 注入。优先考虑 action 打开的弹出面板或侧边栏这样页面怎么变都不会影响你自己的 UI。只有必须贴近内容操作的功能比如划词解释、输入框补全才做 DOM 注入并且每个注入点都要考虑被页面更新清掉的情况。5. 上架之后才暴露的问题审核、更新和兼容性5.1 商店审核为什么容易被拒本地能跑不等于商店能过。审核主要看三件事权限是否最小化。不要申请不使用的权限。隐私政策是否清晰。使用 AI 服务时页面内容会被发送给第三方 API必须告诉用户。是否存在远程代码。扩展不能加载并执行远程脚本。如果申请了“读取所有网站数据”但实际功能只是聊天很容易被要求解释。建议按实际功能拆权限只读当前活动标签页、只在用户点击时注入、只针对特定域名。权限越少审核通过率越高用户信任度也越高。如果 AI 请求会把当前页面正文传给第三方模型扩展商店会要求你说明数据如何收集、用途是什么、是否保留。隐私政策里要写清楚这一点不要用含糊的语言。5.2 扩展更新带来的坑用户安装的扩展不一定自动更新到最新版即使更新了也可能出现manifest 权限变更导致旧功能失效。service worker 注册异常。用户缓存了旧版 content script新旧逻辑同时执行。建议在代码里做版本兼容判断。权限变更要在商店描述和更新日志里写明。更新后自动检查版本号提示用户刷新页面。重要功能不要一次性删除旧接口至少保留一个过渡周期。这里有一个容易被忽略的实际问题扩展更新后旧页面里的 content script 可能还在运行旧代码新的消息格式已经改了两边对不上功能就“莫名其妙”坏掉。调试时记得先强制刷新页面把旧的 content script 清掉。5.3 不同浏览器差异Chrome 是 MV3 的主力Edge 基本兼容但 Firefox 对部分 API 支持不完全一样Safari 扩展开发模式也不同。如果目标是多浏览器建议先以 Chrome 为主跑通完整链路。抽象一层浏览器 API 封装统一处理 storage、tabs、runtime 的差异。每个浏览器都实际跑一遍核心场景不要只做语法兼容。比如有些浏览器对 chrome.storage.session 的支持时机不一致有些浏览器对 service worker 的休眠策略不同。这些只有真机测试才能发现。6. 我的排查顺序和上线检查清单6.1 从最小路径开始验证遇到复杂问题我一般不会直接去改 AI 参数而是先做最小路径验证。第一版不接 AI 模型也不写复杂 UI只做四步在某个页面手动触发一个按钮。content script 发送一条固定消息。background 收到后打印日志并返回固定字符串。页面显示这个字符串。这一步跑通说明扩展的基础链路正常。然后把固定字符串换成 AI API 请求再验证。这样出现问题时能很快分清是扩展链路的问题还是 AI 服务那边的问题不用同时怀疑很多东西。6.2 上线前验证三类关键指标建议至少测三组指标启动成功率扩展安装后service worker 能否稳定注册background 是否持续可用。单请求成功率从页面触发到拿到结果的成功率多测几十次记录失败原因。完整会话成功率连续多轮对话消息顺序、上下文、流式输出是否都正确。另外要观察资源占用。AI 请求如果每次都把大段页面内容转发出去内存和网络成本会快速上升。用户浏览器变卡很多时候不是因为扩展本身复杂而是把整页 HTML 都送给了模型。6.3 上线前检查清单下面是我自己会逐项过一遍的清单manifest 权限是否最小有没有写下不用的权限。AI 密钥有没有暴露在前端代码里。请求有没有超时和失败提示。是否处理 429、网络断开、接口 5xx。会话历史是否保存到 storage 或后端。多标签页同时使用时会不会互相覆盖结果。UI 注入是否会被 SPA 路由清掉。隐私政策是否写明数据会发送给 AI 服务。商店描述是否说明权限用途和 AI 功能边界。有没有日志接口能定位是扩展问题、网络问题还是模型问题。如果让我再做一次这个项目我会先把“哪里触发、AI 看到什么、返回显示在哪、会话存哪里”四个问题画成一张图再动笔写代码。很多看起来是 AI 能力不够的问题最后追查下来都是扩展架构的基础能力没打牢。踩过几次之后我发现最大的问题不是模型不够聪明而是浏览器扩展这个容器本身的限制没有提前规划好。