Claude Code 开发 Chrome 插件教程：从需求、源码到打包发布

用 Claude Code 开发 Chrome 插件，关键不是让 AI 一次性生成所有源码，而是把插件拆成需求、Manifest V3 架构、源码模块、权限声明、调试验证和发布材料几个阶段。Chrome 插件涉及浏览器权限、页面注入、后台 service worker 和商店审核，比普通网页项目更需要清晰边界。

本文会从零讲清如何用 Claude Code 开发一个 Chrome 插件，从需求到源码再到打包发布。还没有配置 Claude Code 或本地开发环境的读者，可以先看本站 安装部署教程 和 环境配置教程；想把 AI 编程应用到真实项目，可以继续参考 实战工作流。

摘要

Claude Code 开发 Chrome 插件的推荐流程是：先写清插件需求，包括功能入口、是否需要 popup、是否需要 content script、是否读取当前网页、需要哪些 Chrome API 和 host permissions；再让 Claude Code 按 Manifest V3 生成插件骨架，包括 manifest.json、service worker、content script、popup.html、popup.js、options 页面和 assets；接着分批实现功能，例如页面信息读取、按钮交互、消息通信、storage 存储和设置项；每批改动后在 chrome://extensions 中开启开发者模式，使用 Load unpacked 加载未打包插件，检查 popup 控制台、service worker 日志和 content script 行为；发布前检查最小权限、隐私说明、图标、截图、版本号、zip 结构和 Chrome Web Store 政策要求。整个过程要让 Claude Code 先给计划，再改文件，并且所有权限和远程请求都要人工审查。

正文

先明确 Chrome 插件要解决什么问题

Chrome 插件不是普通网页。它可以读取当前页面、注入脚本、调用浏览器 API，也可能触发用户权限提示。所以第一步必须定义功能边界：它要在什么页面运行、是否读取 DOM、是否修改页面、是否保存数据、是否需要后台任务、是否需要请求外部接口。

我要开发一个 Chrome 插件。
功能：读取当前页面的 title、description、H1 和图片 alt，生成 SEO 检查结果。
入口：popup 页面点击按钮后执行。
权限：只在当前标签页运行，不默认访问所有网站。
限制：不保存用户隐私数据，不上传网页内容，不注入远程脚本。

第一步：理解 Manifest V3 架构

Chrome 官方文档说明，manifest.json 是扩展唯一必须具有特定文件名的文件。Manifest V3 中，后台逻辑通常由 service worker 承担；content scripts 用于访问页面 DOM；popup 或 options 页面负责用户界面；permissions 和 host_permissions 决定插件能调用哪些能力和访问哪些站点。

你可以先让 Claude Code 解释架构，而不是马上写文件：

请先设计这个 Chrome 插件的 Manifest V3 架构，不要写文件。
请说明：
1. manifest.json 需要哪些字段
2. 是否需要 service worker
3. 是否需要 content script
4. popup 页面负责什么
5. 需要哪些权限，为什么
6. 哪些权限可以避免申请

第二步：生成插件源码骨架

确认架构后，再让 Claude Code 生成源码骨架。一个轻量插件通常包含 manifest.json、popup.html、popup.js、content.js、background.js 或 service-worker.js、styles.css 和 icons。

请生成 Chrome 插件源码骨架，使用 Manifest V3。
文件结构：
- manifest.json
- popup.html
- popup.js
- content.js
- service-worker.js
- styles.css
- icons/
要求：先做最小可运行版本，点击 popup 按钮后读取当前页基础 SEO 信息。

第三步：写 manifest.json

manifest.json 要保持最小权限。Chrome 官方权限文档强调，某些 API 需要 permissions，访问网站还可能需要 host permissions，权限越多越容易触发用户警告和商店审核问题。

{
  "manifest_version": 3,
  "name": "Page SEO Checker",
  "version": "1.0.0",
  "description": "Check basic SEO signals on the current page.",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "service-worker.js"
  }
}

不要默认申请 <all_urls>。如果只需要用户点击后读取当前标签页，优先考虑 activeTab 和必要的 scripting 权限。

第四步：实现 popup 页面

popup 是用户最直观看到的界面。它应该简洁：一个检查按钮、结果区域、错误提示和必要的设置入口。不要在 popup 里塞复杂业务逻辑，可以把页面读取交给 content script，把后台任务交给 service worker。

请实现 popup 页面：
1. 一个“检查当前页面”按钮
2. 显示 title、description、H1 数量、缺少 alt 的图片数量
3. 显示问题和建议
4. 错误时给出清晰提示
5. 样式简洁，不依赖外部 CDN

第五步：实现 content script

content script 运行在网页上下文中，适合读取 DOM。它不应该做过多业务计算，也不应该上传用户页面内容。读取结果可以通过消息发送给 popup 或 service worker。

请实现 content.js：
- 读取 document.title
- 读取 meta[name="description"]
- 统计 h1、h2 数量
- 统计 img 中缺少 alt 的数量
- 返回结构化 JSON
- 不修改页面 DOM
- 不发送外部网络请求

第六步：处理 popup、content script 和 service worker 通信

Chrome 插件常见问题之一是消息通信。popup 负责发起动作，content script 负责读取页面，service worker 负责后台事件和 API 协调。让 Claude Code 写通信逻辑时，要明确消息类型、返回结构和错误处理。

请实现消息通信：
1. popup 点击按钮后向当前 tab 注入或调用 content script
2. content script 返回 SEO 检查结果
3. popup 展示结果
4. 如果当前页面不允许注入，显示错误提示
5. 所有消息都有 type 字段，便于维护

第七步：本地加载和调试插件

打开 chrome://extensions，开启 Developer mode，点击 Load unpacked，选择插件源码目录。加载后测试 popup、当前页读取、content script 日志和 service worker 日志。

chrome://extensions
Developer mode -> On
Load unpacked -> 选择插件目录

如果 popup 没反应，分别检查 popup 控制台、service worker inspection、当前页面控制台和 manifest 权限。不要只看 Claude Code 的总结，必须在浏览器中实际验证。

第八步：让 Claude Code 根据错误日志修复

调试时，把 Chrome 控制台报错原样贴给 Claude Code，并要求它先分析，不要直接扩大修改范围。

插件加载后点击按钮报错：
【粘贴 popup 或 service worker 日志】
请先分析原因，不要马上大范围重构。
请说明：
1. 报错来自哪个文件
2. 是否是权限、消息通信或注入脚本问题
3. 最小修改方案
4. 修改后如何验证

第九步：检查权限和隐私

发布前必须检查权限。权限申请越多，用户越不信任，也越容易在审核中被要求解释。Chrome 官方文档也提醒，添加或更改 host permissions 与 content script matches 可能触发安装警告。

让 Claude Code 做一次权限审查：

请审查 manifest 权限：
1. 每个 permission 的用途是什么
2. 是否可以删除或缩小范围
3. 是否需要 host_permissions
4. 是否会触发用户安装警告
5. 是否涉及隐私说明
6. 是否有远程代码或外部请求风险

第十步：准备图标、截图和说明文案

Chrome Web Store 发布不仅需要代码，还需要图标、截图、说明文案、隐私说明和版本信息。让 Claude Code 生成文案时，要避免夸大功能，不要承诺无法验证的结果。

第十一步：打包发布

发布前检查目录，不要把 node_modules、.git、测试日志、真实密钥、临时截图和本地配置打包进去。zip 包根目录应包含 manifest.json，而不是多套嵌套目录。

page-seo-checker.zip
├── manifest.json
├── popup.html
├── popup.js
├── content.js
├── service-worker.js
├── styles.css
└── icons/

第十二步：完整提示词模板

下面这段可以直接复制给 Claude Code：

请帮我开发一个 Chrome 插件，使用 Manifest V3。
当前阶段先给计划，不要立即写文件。

插件需求：
【写清功能，例如读取当前页面 SEO 信息】

功能入口：
【popup / content script / options / side panel】

权限限制：
- 使用最小权限
- 不默认申请 <all_urls>
- 不上传用户网页内容
- 不注入远程脚本
- 不保存敏感信息

请先输出：
1. Manifest V3 架构方案
2. 文件目录结构
3. manifest.json 权限说明
4. popup、content script、service worker 分工
5. 本地调试步骤
6. 打包发布检查清单
等我确认后再生成源码。

开发 Chrome 插件时不要做的事

不要为了省事申请过宽权限，不要在扩展里硬编码密钥，不要执行远程脚本，不要未经说明上传用户页面内容，不要跳过隐私说明，不要把开发日志和本地配置打进 zip。更多错误排查可以查看本站 问题排查教程。

FAQ

Claude Code 能直接生成 Chrome 插件源码吗？

可以，但建议先让它输出 Manifest V3 架构和权限说明，再分批生成 manifest、popup、content script 和 service worker。

Manifest V3 和旧版有什么关键区别？

Manifest V3 使用 service worker 处理后台事件，权限声明和内容安全策略也更严格。开发时要特别注意后台脚本不是长期常驻的。

为什么不要默认申请所有网站权限？

过宽权限会触发用户警告，也会增加审核和隐私风险。能用 activeTab 解决的场景，就不要默认申请所有站点访问权限。

插件本地怎么测试？

进入 chrome://extensions，开启 Developer mode，使用 Load unpacked 加载插件目录，然后检查 popup、当前页面、content script 和 service worker 日志。

发布前最容易遗漏什么？

最容易遗漏权限解释、隐私说明、图标截图、版本号、zip 目录结构和移除开发文件。发布前应逐项检查。