moai-platform-chrome-extension

Chrome Extension Manifest V3 开发

快速参考

Chrome Extension Manifest V3 开发专家可帮助使用最新的 Chrome 平台 API 构建现代浏览器扩展。

自动触发：检测到 Chrome 扩展项目，例如包含 manifest_version 3 的 manifest.json、service worker 文件、内容脚本声明或 chrome API 使用模式

核心能力

Manifest V3 平台：

• Service worker 取代持久化后台页面，支持事件驱动架构
• 移除远程代码执行功能，增强安全性
• declarativeNetRequest 取代阻塞式 webRequest，用于网络过滤
• 所有 chrome.* API 均采用基于 Promise 的方法
• action API 将 browserAction 和 pageAction 统一为一个接口
• 支持 Chrome 88 及更高版本

进程架构：

• Service worker 作为单个事件驱动的后台脚本运行，空闲时会终止
• 内容脚本在隔离环境中的网页上下文内执行
• 弹出窗口和侧边栏提供专用 UI 界面
• 选项页面提供扩展设置界面
• DevTools 面板扩展 Chrome Developer Tools

通信模式：

• Service worker 与内容脚本之间通过 sendMessage 发送一次性消息
• 通过 connect 建立长期连接，并使用基于端口的通信
• 通过 externally_connectable 声明实现跨扩展消息传递
• 网页与扩展之间可针对已验证的来源进行消息传递

安全模型：

• 内容安全策略将脚本来源限制为仅限自身
• 不允许内联脚本或远程代码执行
• 权限声明安装时所需的 API 访问权限
• 可选权限允许在运行时请求访问权限，并需用户同意
• 主机权限控制网页访问模式

Context7 文档访问

如需获取最新的 Chrome Extension API 文档，请使用 Context7 MCP 工具：

步骤 1 - 解析库 ID：使用 mcp__context7__resolve-library-id 并以 "chrome extension" 为查询内容，获取兼容 Context7 的库 ID。

步骤 2 - 获取文档：使用 mcp__context7__get-library-docs，并指定已解析的库 ID、主题和 token 分配量。

主题示例包括 "manifest v3 configuration"、"service worker lifecycle"、"content scripts injection"、"message passing patterns"、"chrome.storage API"、"side panel API" 和 "declarativeNetRequest rules"。

---

模块索引

此技能采用渐进式披露方式，并提供专门模块以介绍详细的实现模式。

核心模块

manifest-v3-reference 涵盖 Manifest V3 扩展程序的完整 manifest.json 字段参考。主题包括必需字段和可选字段、字段类型和约束、权限声明、从 MV2 迁移到 MV3 的说明，以及扩展程序配置最佳实践。

service-worker-patterns 涵盖服务工作线程的生命周期、事件注册、状态管理和调试。主题包括事件驱动架构、顶层监听器注册、使用 chrome.storage 持久化状态、保持运行策略、用于访问 DOM 的离屏文档，以及使用 chrome://extensions 进行调试。

content-scripts-guide 涵盖内容脚本注入方法、隔离世界和通信。主题包括在 manifest 中静态声明、使用 chrome.scripting 动态注册、编程式注入、隔离世界架构、DOM 访问模式和安全注意事项。

messaging-patterns 涵盖扩展程序组件之间的消息传递。主题包括使用 sendMessage 发送一次性消息、使用 connect 和端口建立长连接、异步响应模式、跨扩展程序消息传递、网页消息传递和错误处理策略。

apis-quick-reference 涵盖主要 chrome.* API 的方法签名和权限要求。主题包括 chrome.runtime、chrome.tabs、chrome.storage、chrome.action、chrome.scripting、chrome.alarms、chrome.notifications、chrome.contextMenus、chrome.sidePanel、chrome.declarativeNetRequest、chrome.offscreen、chrome.identity 和 chrome.commands。

ui-components 涵盖弹出窗口、侧边面板、选项页面、DevTools 面板和内容脚本 UI。主题包括弹出窗口 HTML 和生命周期、侧边面板配置和 API、选项页面模式、DevTools 扩展程序集成，以及由内容脚本注入的 UI。

security-csp 涵盖内容安全策略、权限模型和安全编码实践。主题包括扩展程序页面的 CSP 配置、最小权限、输入验证、XSS 防护、安全消息传递模式和 HTTPS 强制要求。

publishing-guide 涵盖 Chrome Web Store 提交和分发。主题包括开发者账号设置、扩展程序打包、隐私政策要求、审核流程、更新机制和自托管分发。

---

实现指南

Manifest V3 结构

每个 Chrome 扩展程序都需要在项目根目录中包含一个 manifest.json 文件。三个字段为必填项：manifest_version 设置为整数 3，name 作为扩展程序的显示名称且最多 75 个字符，version 为符合 semver 的字符串。

description 字段提供摘要，显示在 Chrome Web Store 中，最多 132 个字符。icons 对象指定用于各种 Chrome UI 场景的 PNG 图标，尺寸为 16、32、48 和 128 像素。

如需进行后台处理，请在 background 对象中声明 service_worker 字段，并将其设置为指向服务工作线程文件的单个字符串路径。使用 ES 模块导入时，将 type 设置为 module。服务工作线程路径必须是单个字符串，不能是数组。

内容脚本以对象数组的形式声明，每个对象都指定用于 URL 匹配的 matches 模式、用于 JavaScript 文件的 js 数组、用于样式表的可选 css 数组，以及用于控制注入时机的 run_at，其值可以是 document_start、document_end 或 document_idle。

如需了解详细的字段参考和迁移指南，请参阅 modules/manifest-v3-reference.md。

服务工作线程架构

Manifest V3 中的服务工作线程以事件驱动模式取代了持久后台页面。服务工作线程仅在响应事件时运行，并会在空闲时终止，从而减少内存和 CPU 消耗。

所有事件监听器都必须在服务工作线程脚本的顶层注册。在回调、Promise 或异步函数中注册的监听器无法在服务工作线程重启后继续生效。

由于服务工作线程无法访问 DOM、没有 window 对象，也没有 localStorage，因此请使用 chrome.storage API 保存持久状态。对于定时任务，请使用 Alarms API，而不要使用 setTimeout 或 setInterval，因为这些计时器无法在服务工作线程终止后继续运行。网络请求请使用 fetch，而不要使用 XMLHttpRequest。

对于需要访问 DOM 的长时间运行操作，请通过 chrome.offscreen.createDocument 使用 Offscreen Documents API 创建具备 DOM 功能的隐藏文档。

有关完整的服务工作线程模式和调试指南，请参阅 modules/service-worker-patterns.md。

内容脚本

内容脚本会在网页上下文中执行 JavaScript 和 CSS。它们运行在隔离世界中，这意味着它们可以与宿主页面共享 DOM 访问权限，但拥有独立的 JavaScript 执行环境，从而避免变量和函数冲突。

共有三种注入方式。静态注入通过 manifest 中的 content_scripts 数组和 URL 匹配模式声明脚本。动态注入使用 chrome.scripting.registerContentScripts 在运行时注册脚本。编程式注入使用 chrome.scripting.executeScript 按需注入，并且需要 host_permissions 或 activeTab 权限。

内容脚本可直接访问的 chrome API 有限：仅包括 dom、i18n、storage，以及特定的 runtime 方法，包括 connect、sendMessage、onMessage、onConnect、getManifest、getURL 和 id。所有其他 API 调用都必须通过消息传递发送给服务工作线程。

有关注入模式、隔离世界的详细说明和安全注意事项，请参阅 modules/content-scripts-guide.md。

消息传递模式

扩展程序使用 Chrome 消息传递机制在各组件之间通信。单次消息使用 chrome.runtime.sendMessage 将消息发送给服务工作线程，使用 chrome.tabs.sendMessage 将消息发送给内容脚本。每条消息都会通过回调或 Promise 收到单个响应。

长连接使用 chrome.runtime.connect 或 chrome.tabs.connect 建立端口。直到任一端调用 disconnect、监听器被移除或所在标签页卸载后，端口才会关闭。端口支持持续的双向通信。

对于单次消息传递中的异步响应，onMessage 监听器必须返回 true，以表明会异步调用 sendResponse；或者从 Chrome 144 开始，直接返回一个 Promise。

所有消息都使用 JSON 序列化，最大大小为 64 MiB。切勿信任来自内容脚本的消息内容，因为宿主页面上下文可能已遭入侵。

有关完整的消息传递模式，包括跨扩展程序和网页通信，请参阅 modules/messaging-patterns.md。

Chrome API 参考

chrome.runtime API 提供扩展程序生命周期管理、消息传递和清单访问功能。它处理安装、更新和挂起事件，并提供获取扩展程序 URL 和平台信息的方法。

chrome.tabs API 管理浏览器标签页，提供查询、创建、更新和移除标签页的方法。chrome.storage API 提供三个存储区域：容量为 10 MB 的 local、容量为 100 KB 且可在已登录设备间同步的 sync，以及浏览器重启时会清空的内存存储 session。

chrome.action API 控制工具栏按钮，包括徽章文本、图标、弹出窗口和点击处理程序。chrome.scripting API 提供向网页以编程方式注入脚本和 CSS 的功能。

chrome.sidePanel API 管理扩展程序侧边栏，这是一个与网页内容并列的持久 UI 界面。chrome.declarativeNetRequest API 使用静态和动态规则过滤网络请求，而无需阻塞 webRequest。

有关完整的 API 方法签名和权限要求，请参阅 modules/apis-quick-reference.md。

UI 组件

扩展程序支持多种 UI 界面。弹出窗口通过清单中的 action.default_popup 配置，点击工具栏按钮时会以标准 HTML 页面形式显示。弹出窗口失去焦点后会关闭，因此应快速加载。

侧边栏通过清单中的 side_panel.default_path 配置，在网页内容旁提供一个持久面板。chrome.sidePanel API 控制面板行为，可启用按标签页或全局显示的面板。

选项页面通过 options_ui.page 配置，并在 chrome://extensions 中打开，用于设置扩展程序。DevTools 面板通过 devtools_page 清单字段扩展 Chrome Developer Tools。

内容脚本可以使用 DOM 操作直接向网页注入 UI 元素，并应用自定义 CSS 设置样式。

有关 UI 实现模式的详细信息，请参阅 modules/ui-components.md。

权限模型

权限分为四类。标准权限声明 API 访问要求，例如 storage、tabs、activeTab、contextMenus、notifications、scripting、alarms、sidePanel、declarativeNetRequest、identity 和 offscreen。这些权限会在安装时授予。

主机权限使用 https://.example.com/ 之类的模式指定网页访问的 URL 模式。可选权限和可选主机权限允许在运行时通过 chrome.permissions.request 请求权限，从而减少安装时的权限提示。

优先使用 activeTab，而不是宽泛的主机权限，以尽量减少权限警告。只请求扩展程序功能所必需的最低限度权限。

有关详细的权限策略和安全指南，请参阅 modules/security-csp.md。

安全最佳实践

Manifest V3 的内容安全策略将 script-src 限制为 self 和 wasm-unsafe-eval。禁止使用内联脚本、eval 和远程代码加载。所有 JavaScript 都必须打包在扩展程序包中。

内容脚本运行在隔离环境中，但应将其视为可能已遭入侵，因为宿主页面可以操纵共享 DOM。务必在服务工作线程中验证并清理从内容脚本接收的数据。切勿对不可信数据使用 eval、document.write 或 innerHTML。所有外部网络请求都应使用 HTTPS。

有关全面的安全模式和 CSP 配置，请参阅 modules/security-csp.md。

---

高级模式

如需了解高级主题的详细实现指南，请参阅 modules 目录：

Manifest V3 迁移：

• 将 MV2 后台页面转换为服务工作线程
• 使用 declarativeNetRequest 替代阻塞式 webRequest
• 将远程代码更新为打包模块
• 将持久状态适配为 chrome.storage 模式

复杂的服务工作线程模式：

• 为周期性任务安排多个闹钟
• 为长时间运行的操作保持服务工作线程活动
• 管理用于音频、画布和 DOM 解析的离屏文档
• 在服务工作线程和内容脚本之间共享模块导入

高级内容脚本模式：

• 根据用户偏好动态注册脚本
• 针对主世界与隔离世界的隔离策略
• 注入 Shadow DOM，封装 UI 组件
• 使用 MutationObserver 处理动态页面内容

跨上下文通信：

• 在多个内容脚本之间路由消息
• 向所有标签页广播的模式
• 外部网站与扩展程序通信
• 通过 chrome.runtime.connectNative 与本地应用进行原生消息传递

存储同步：

• 使用 chrome.storage.sync 同步跨设备设置
• 使用 chrome.storage.session 存储临时数据
• 通过存储变更监听器实现响应式更新
• 配额管理和溢出策略

---

故障排除

常见问题及解决方案：

服务工作线程未注册：

确认 manifest.json 中的 background.service_worker 字段是单个字符串路径，而不是数组。确保服务工作线程文件存在于声明的路径中。检查 chrome://extensions 中扩展程序卡片上的错误消息。在扩展程序详情页点击服务工作线程链接，检查其控制台。

内容脚本未注入：

确认 manifest.json 中的 matches 模式正确匹配目标 URL。确认 run_at 时机适合要访问的页面内容。检查扩展程序是否具有所需的主机权限。检查目标页面的控制台中是否存在内容脚本错误。

消息传递失败：

确保发送方和接收方的通道名称与消息结构一致。确认接收监听器已在发送消息前注册。检查 sendResponse 是否在监听器返回前调用；对于异步响应，则应返回 true。使用 chrome.tabs.sendMessage 时，确认目标标签页存在。

权限被拒绝错误：

确认 manifest.json 中声明了所有必需权限。对于程序化注入，确认已授予 host_permissions 或 activeTab 权限。检查 chrome://extensions 中是否有权限警告或禁用状态。使用 chrome.permissions.contains 验证运行时权限。

扩展程序未显示在 Chrome Web Store 中：

确保 manifest.json 通过验证且没有错误。确认软件包中包含所有已声明的资源，包括图标、HTML 文件和脚本。检查描述是否未超过 132 个字符。查看开发者控制面板中的提交错误。

调试命令：

打开 chrome://extensions 查看所有已安装的扩展程序及其状态。启用开发者模式以访问扩展程序详情和错误日志。点击服务工作线程链接，打开其专用 DevTools 控制台。使用 chrome://inspect 在页面上下文中调试内容脚本。

---

配合使用效果良好

• .claude/rules/moai/languages/typescript.md，用于扩展程序开发中的 TypeScript 模式（通过 paths frontmatter 自动加载）
• .claude/rules/moai/languages/javascript.md，用于 JavaScript 模式和 ES 模块用法（通过 paths frontmatter 自动加载）
• moai-domain-frontend，用于基于 React 或框架的弹出窗口和侧边面板 UI
• moai-domain-backend，用于服务器端 API 集成
• moai-workflow-testing，用于扩展程序测试策略

---

资源

模块参考

如需了解详细的实现模式，请参阅 modules 目录：

• modules/manifest-v3-reference.md 涵盖完整的 manifest.json 字段参考
• modules/service-worker-patterns.md 涵盖 service worker 生命周期和模式
• modules/content-scripts-guide.md 涵盖内容脚本注入和通信
• modules/messaging-patterns.md 涵盖所有消息传递模式
• modules/apis-quick-reference.md 涵盖 chrome.* API 方法签名
• modules/ui-components.md 涵盖弹出窗口、侧边栏、选项和 DevTools UI
• modules/security-csp.md 涵盖 CSP、权限和安全编码
• modules/publishing-guide.md 涵盖 Chrome 网上应用店发布工作流

外部文档

如需获取最新文档，请使用 Context7 查询：

• /nicedoc/chrome-extension-doc：Chrome 扩展 API

如需查阅 Chrome 官方文档，请使用 WebFetch：

• https://developer.chrome.com/docs/extensions/develop：开发指南
• https://developer.chrome.com/docs/extensions/reference/api：API 参考

---

状态：已可用于生产环境 生成工具：MoAI-ADK Skill Factory v1.0 最后更新：2026-02-01 版本：1.0.0（首次发布） 覆盖范围：Manifest V3、Service Worker、内容脚本、消息传递、Chrome API、UI、安全、发布

常见的自我辩解

自我辩解	事实
“我会先请求宽泛的权限，之后再缩小范围”	用户在安装时就会看到权限。宽泛的权限会阻碍安装，还可能导致 Chrome 网上应用店拒绝上架。
“内容脚本可以访问页面上的所有内容，所以安全问题应由页面负责”	内容脚本运行在用户的上下文中。通过内容脚本注入不可信内容，会为扩展带来 XSS 攻击向量。
“Manifest V2 仍然可用，我不需要迁移”	Chrome 网上应用店不再接受 MV2 提交。未来的 Chrome 版本将停用 MV2 扩展。
“Service Worker 和后台页面是一样的”	Service Worker 由事件驱动，空闲时会终止。持久状态必须使用 chrome.storage，而不能使用全局变量。
“我之后再添加 CSP，它只是一个安全标头”	manifest.json 中缺少 CSP 会允许内联脚本和 eval()，它们是扩展的主要攻击向量。

危险信号

• manifest.json 在没有正当理由的情况下请求 <all_urls> 或 *://*/* 主机权限
• 内容脚本对不可信内容使用 eval() 或 innerHTML
• Service Worker 将状态存储在全局变量中（终止时会丢失）
• manifest.json 中缺少 content_security_policy
• 扩展在未验证来源的情况下与外部服务通信

验证

• manifest.json 中的权限已精简，且每项权限都有文档说明其合理性
• manifest.json 中已定义内容安全策略（不含 unsafe-eval、unsafe-inline）
• Service Worker 使用 chrome.storage 保存持久状态（不使用全局变量保存状态）
• 消息传递在处理前会验证发送方来源
• 已在启用开发者模式的 Chrome 中测试扩展（显示测试结果）
• 已验证符合 Manifest V3（未使用仅适用于 MV2 的 API）

遥测窗口

状态：不明确（60 天窗口） R4 审计结论：保留（监控） SPEC：SPEC-V3R2-WF-001 §6.2 (REQ-WF001-013) 窗口开始：2026-04-25（Wave 1.5 提交日期） 窗口结束：2026-06-24（60 天） 重新审计触发条件：此技能的 SessionStart 钩子激活次数 决策标准：

• 如果窗口期内激活次数 >= 5 → 永久保留
• 如果窗口期内激活次数 = 0 → 在 v3.1 中安排退役
• 如果 0 < 次数 < 5 → 保留并添加“低使用率”标签