Chrome 插件开发指南：从 Web 到扩展及实战

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，一起把插件做得更好用。