chrome-extensions

关于 Chrome 扩展

本指南介绍如何使用 Manifest V3 构建符合生产标准的 Chrome 扩展，并将其发布到 Chrome Web 商店。无论是在创建、修改、调试 Chrome 浏览器扩展及相关 chrome.* API，还是理解内容脚本、服务工作线程、弹出窗口、侧边面板、声明式 NetRequest、搜索框、上下文菜单及用户脚本时，亦或是处理权限说明与隐私政策等与 Web 商店发布相关的任务，都需要参考本指南。

在构建部分，一系列强制性的规则被列出，旨在解决扩展出错的最常见原因。相关示例包括：仅引用实际存在的图标文件（或完全不使用图标）、明确指定打开侧边面板的触发条件（仅提供 default_path 无法实现自动打开）、由于扩展的 CSP 策略限制了 eval 和内联脚本的执行，因此只能在沙箱化的 iframe 中运行代码、在读取 tab.url 之前先声明对标签页的权限、始终使用 async/await 代替 .then() 链式调用、在内容脚本中批量处理 DOM 操作以避免阻塞主线程，以及由于服务工作线程为临时进程，切勿将其变量中存储状态（应使用 chrome.storage 进行持久化存储，或通过 chrome.alarms 替代 setTimeout）。此外，还有规则涉及通过清单密钥为 chrome.identity OAuth 确保扩展 ID 的稳定性、在上下文菜单操作后向用户反馈、在服务工作线程、弹出窗口及侧边面板中统一使用 Extension-Available LanguageModel（Prompt API），以及在使用 chrome.action 之前必须在清单中指定动作密钥。

当你希望开发的扩展首次使用即可正常运行并通过审核，而非花费时间调试 Manifest V3 中那些细微的问题时，就可以参考本指南。每条规则都会对比出错代码与正确代码，并指向对应的详细参考文档（涵盖图标、侧边面板、CSP 沙箱、标签页管理、内容脚本、服务工作线程、身份认证、上下文菜单以及 Prompt API 等主题）。指南的另一部分则讲解如何将扩展发布到 Chrome Web 商店，内容包括准备扩展包、应对审核拒绝、撰写权限说明以及起草隐私政策，因此从首次构建到上架商店的整个生命周期中都能发挥作用。

常见问题

何时应该使用这项技能？

在创建、修改、调试 Chrome 扩展及相关 Chrome 扩展 API，或是准备将扩展发布到 Chrome Web 商店时都需要使用，其中包括撰写权限说明和隐私政策的相关工作。

为什么在清单中定义了侧边面板却无法打开？

仅定义 side_panel.default_path 并不能让侧边面板自动打开；必须通过点击操作或弹出窗口按钮添加触发逻辑，例如调用 chrome.sidePanel.open()，或者设置 openPanelOnActionClick 参数。

为什么我的扩展状态会丢失？

服务工作线程属于临时进程，大约 30 秒无操作后就会终止，因此存储在变量中的状态会丢失；应使用 chrome.storage 进行持久化存储，并在每次事件发生时读取数据，同时用 chrome.alarms 替代 setTimeout/setInterval。

鉴于扩展的 CSP 策略，如何运行动态代码？

扩展的 CSP 策略会阻止 eval、new Function 以及内联脚本的执行，因此只能通过清单中配置的沙箱环境加上 postMessage 机制，在沙箱化的 iframe 中运行代码，或者通过生成独立源站的 Blob URL 或 srcdoc 方式来执行代码。

本指南是否涵盖 Prompt API？

是的。LanguageModel API 可以在服务工作线程、弹出窗口及侧边面板中正常使用，无需额外权限，而且扩展还能使用 LanguageModel.params() 方法，而该方法在普通网页环境中是不可用的。

所有文件

23 个文件 references/extensions/context-menus.md 1.8 KB 查看 references/extensions/auth-identity.md 3.9 KB 查看 references/extensions/declarative-net-request.md 2.7 KB 查看 references/extensions/message-passing.md 4.1 KB 查看 references/extensions/api-calling.md 2.1 KB 查看 references/extensions/csp-sandbox.md 4.7 KB 查看 references/extensions/media-capture.md 4.7 KB 查看 references/extensions/prompt-api.md 3.7 KB 查看 references/extensions/tab-management.md 3.7 KB 查看 SKILL.md 25.5 KB 查看 references/extensions/content-scripts.md 3.4 KB 查看 references/extensions/devtools.md 2.8 KB 查看 references/extensions/omnibox.md 1.8 KB 查看 references/extensions/side-panel.md 4.4 KB 查看 references/webstore/chromewebstore-template.md 5.6 KB 查看 references/webstore/review-checklist.md 6.8 KB 查看 references/extensions/icons.md 2.7 KB 查看 references/extensions/popup-ui.md 2.3 KB 查看 references/extensions/storage.md 1.9 KB 查看 references/webstore/store-listing.md 7.8 KB 查看 references/extensions/service-worker.md 4.5 KB 查看 references/extensions/user-scripts.md 9.1 KB 查看 references/webstore/privacy-policy.md 4.1 KB 查看