Chrome 插件开发指南：从 Web 到扩展，以及「网页内容总结助手」实战

本文结合开源项目 网页内容总结助手（React + Vite + Manifest V3）总结插件开发中的注意点，并对比插件开发与普通 Web 开发的差异，方便从前端转型或入门扩展开发的同学少踩坑。

一、先安利一下：网页内容总结助手

网页内容总结助手 是一款基于 React + Vite 构建的 Chrome 扩展，主打「一键总结网页并导出 Markdown」：

• 一键提取正文并调用 ModelScope + DeepSeek 做 AI 总结，或使用本地 mock
• 选择页面任意区域进行总结（高亮选择模式）
• 多种输出类型：总结、博客、文章、报告、要点列表
• 设置本地持久化：API Key、总结字数等存于 chrome.storage.sync，无需后端
• 遵循 Manifest V3，适合作为学习或二次开发模板

如果你在做阅读摘要、知识整理或内容再生产，欢迎在 Chrome 应用商店或通过「加载已解压的扩展程序」安装使用，也欢迎 Star / Fork 项目参与改进。

下面进入正题：插件开发要注意什么，和普通 Web 开发有什么不同。

二、插件开发 vs Web 开发：核心差异

这些差异会直接影响到你的技术选型、构建配置和调试方式，下面按「开发时需要注意的情况」展开。

三、开发插件时需要注意的情况（结合本项目）

1. Manifest：权限与入口要写对

扩展的「合同」是 manifest.json（本项目在 public/manifest.json，构建时拷贝到 dist）。

• permissions：只申请必要权限，例如本插件用到了 activeTab、scripting、downloads、storage。
• host_permissions：调用外部 API 时必须声明域名，例如 ModelScope："https://api-inference.modelscope.cn/*"，否则请求会被拦截。
• content_scripts.js：写的是构建后的文件名（如 content.js），且该文件必须是单文件、无顶层 ESM（见下一条）。

权限过多会触发商店或用户的不信任；少了则功能无法使用，建议每加一个能力就对照 Manifest 文档 补全。

2. Content Script 不能直接用 ES Module

这是从 Web 开发转扩展时最容易踩的坑之一。

• 原因：Content Script 由 Chrome 按「传统脚本」注入到页面，不支持type="module"，遇到顶层 import 会报错：Cannot use import statement outside a module。
• 本项目做法：保留 Vite 打 Popup（ESM），单独用一份 Vite 配置（vite.content.config.js）把 src/content.js 打成 IIFE 单文件，依赖（如 marked）打包进去，产出 dist/content.js。构建命令形如：vite build && vite build --config vite.content.config.js。

若你用的是其它打包器，思路一致：Content 入口单独打包，输出格式为 IIFE（或其它非 ESM），且不拆成多个 chunk（避免注入多个 script）。

3. Popup 与 Content Script：两个世界，靠消息通信

• Popup：点击图标打开的页面，和普通网页一样跑在扩展自己的环境中，可以随意用 React、Vue、ESM。
• Content Script：注入到用户正在浏览的网页里，能访问 DOM，但和 Popup/Background 不共享 JS 变量。

二者只能通过 chrome.runtime.sendMessage / chrome.tabs.sendMessage 通信。例如本插件中：

• Popup 发 startSelection → Content 进入高亮选择模式；
• Content 把选中的文本通过消息回传 → Popup 再调 AI 或 mock 总结。

另外，若 Popup 打开时当前页尚未注入 Content Script，sendMessage 会报「Receiving end does not exist」。本项目在 Popup 里对这类调用做了 try/catch 或 .catch()，必要时先通过 chrome.scripting.executeScript 注入再发消息，避免未捕获异常。

4. 没有「后端」时的配置持久化：chrome.storage

插件可以是纯前端，没有自己的服务器。用户设置（如 API Key、总结字数）需要持久化时，用 chrome.storage 即可。

• chrome.storage.sync：跨设备同步（需用户登录 Chrome），适合设置、偏好。
• chrome.storage.local：仅本机，适合较大或不同步的数据。

本项目把 API Key、总结字数、内容类型等统一存到 chrome.storage.sync。Popup 打开时从 storage 读入并写入 React state；用户在设置页修改后写回 storage，下次打开或其它设备上都会生效。注意：不要在前端代码里写死 API Key，一律从 storage 或用户输入来，并在 UI 上对「未配置 / 密钥错误」做明确提示（如本插件的设置校验与错误文案）。

5. 加载的是「目录」而不是「网址」

和普通 Web 不同，扩展在本地是以目录形式加载的（开发者模式下的「加载已解压的扩展程序」）。因此：

• 构建产物必须包含完整扩展：至少要有 manifest.json、Popup 的 HTML/JS、Content Script 的 JS 等，且路径要和 manifest 里写的一致。
• 本项目使用 Vite，Popup 和 Content 分别构建，最终都输出到 dist，并依赖 public 下的 manifest.json 被拷贝到 dist。加载时选择 dist 目录即可。

开发时若改了代码，需要重新 pnpm run build（或 npm run build），并在 chrome://extensions 里点击扩展的「重新加载」。

6. 调试方式与普通 Web 的差异

• Popup：右键扩展图标 →「检查弹出内容」，会打开该 Popup 的 DevTools，和普通页面一样打断点、看 Network。
• Content Script：在被注入的网页上按 F12，在 Sources 里找到扩展的 content.js，或在 Console 里看到来自 content script 的 log。
• Background（若使用）：在 chrome://extensions 里点击该扩展的「Service Worker」链接打开 DevTools。

Popup 用 npm run dev 可以单独在浏览器里跑 React 界面，但和真实扩展环境（storage、消息、content）仍有差别，完整流程建议以「构建 → 加载 dist」为准做验证。

7. 安全与体验上的小建议

• 权限：只声明真正用到的权限和 host；API Key 等敏感信息只存 storage，不写进源码、不提交仓库。
• 错误与降级：如本插件在「未配置 Key / 密钥错误」时提示并打开设置页；其它 API 失败时可选降级到本地 mock，避免白屏或静默失败。
• 用户提示：总结前可对字数、内容类型做校验；保存设置后给「设置已保存」等反馈，提升可感知的稳定性。

四、小结：从 Web 到插件的心智转换

• 多环境：Popup / Content / Background 各是一块运行环境，用消息和 storage 串联，而不是一个单页应用里的组件通信。
• 构建多入口：至少区分「Popup（可 ESM）」和「Content（要 IIFE）」两套构建，产物放到同一目录供 manifest 引用。
• 权限与存储：manifest 里声明权限和 host；无后端时用 chrome.storage 做配置持久化，并从设计上避免硬编码密钥。
• 调试与发布：以「构建 → 加载 dist → 在真实扩展环境里点一点」为主；发布到商店前再对照审核策略做一遍检查。

如果你正在做或想做一个「和网页内容强相关」的小工具（总结、翻译、高亮、剪藏等），欢迎参考或直接基于 网页内容总结助手 的架构来改：React + Vite、Manifest V3、Content 与 Popup 分离构建、storage 持久化，这些模式都可以复用。也欢迎提 Issue 和 PR，一起把插件做得更好用。

项目仓库：
https://gitee.com/qiaoyuning/ai-page-summarizer.git

本地安装：pnpm install && pnpm run build，在 Chrome 中加载 dist 目录即可使用。