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 开发：核心差异
| 维度 | 普通 Web 开发 | Chrome 扩展开发 |
|---|---|---|
| 运行环境 | 单一页面或 SPA，同源策略限制 | 多个隔离环境：Popup、Background（如 Service Worker）、Content Script、可选 Offscreen |
| 脚本加载方式 | 可自由使用 <script type="module"> | Popup 可用 ESM；Content Script 按普通脚本注入，不能直接写顶层 import |
| 存储 | 常用 localStorage、Cookie、后端 DB | 推荐 chrome.storage.sync / chrome.storage.local，跨页面且可同步（sync） |
| 网络与权限 | 受 CORS 限制，需后端或代理 | 在 manifest 中声明 host_permissions 后可直连指定域名，无 CORS 问题 |
| 与页面交互 | 直接操作当前页 DOM/JS | Content Script 与页面共享 DOM，与 Popup/Background 通过 消息 通信，不能直接共享变量 |
| 构建与部署 | 通常单入口打包，部署到服务器 | 多入口：Popup 页面 + Content Script（+ Background）；加载的是本地目录（如 dist），不是 URL |
| 安全与审核 | 主要防 XSS、CSRF、敏感信息泄露 | 还需注意权限最小化、Manifest V3 规则、商店审核策略 |
这些差异会直接影响到你的技术选型、构建配置和调试方式，下面按「开发时需要注意的情况」展开。
三、开发插件时需要注意的情况（结合本项目）
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 目录即可使用。
