Manifest.json 编译与输出

​

Manifest 能力

​

Extension.js 从哪里读取 manifest

• src/manifest.json（存在时优先）
• 项目根目录下的 manifest.json

​

Extension.js 对它做了什么

1. 从你的源文件输出 manifest 资源。
2. 为当前激活的浏览器目标过滤带浏览器前缀的键。
3. 为扩展产物应用 manifest 覆盖/路径归一。
4. 校验所引用的文件（HTML/脚本/CSS/图标/JSON），缺失时尽早失败。

​

一份 manifest，多种浏览器

• chromium:* 覆盖所有 Chromium 系浏览器，chrome:* 与 edge:* 各自只覆盖一个浏览器
• firefox:*、gecko:*

• chromium:key
• background.firefox:scripts
• background.chromium:service_worker

​

受支持的 manifest 字段

​

权限设计

• 让 permissions 保持小而有意为之。
• 让 host_permissions 收窄到功能确实需要的范围。
• 在可能时，把非核心能力放进 optional_permissions 或 optional_host_permissions。
• 每当 content script 的匹配或 background 能力发生变化时，重新审视权限范围。

​

输出行为

• background.service_worker 会变成 background/service_worker.js
• side_panel.default_path 会变成 sidebar/index.html
• page_action.default_popup 会变成 page_action/index.html，在 Firefox（任意 manifest 版本）与 Chromium MV2 上作为工具栏弹窗旁的独立页面。当 page_action 与 action（或 browser_action）指向同一个文件时，两个键共用 action/index.html。Chromium MV3 没有 page action 界面，因此构建会带警告地从该 manifest 中移除 page_action，并且不输出它的页面。

• content_scripts/content-0.js
• content_scripts/content-0.css

​

Manifest V2 构建会合并 host permissions 并把 CSP 压平

firefox reads a Manifest V2 content_security_policy as one string, so the sandbox slot has nowhere to go.
The build wrote the extension_pages policy as that string and dropped the sandbox policy from the built manifest. Scope the object form with the chromium: prefix, or declare a Manifest V3 build for this browser.

{
  "manifest_version": 2,
  "permissions": ["storage"],
  "host_permissions": ["https://example.com/*"],
  "content_security_policy": {
    "extension_pages": "script-src 'self'"
  }
}

​

开发期行为

• 当 manifest.json 发生变化时，Extension.js 会重新编译并触发扩展的硬重载流程。
• 如果 manifest 入口结构发生变化（例如脚本列表变更），Extension.js 可能要求重启开发服务器。
• manifest 字段所引用的文件缺失会以聚焦于 manifest 的错误使编译失败。

​

变更结果矩阵

​

Extension.js 会替你修复什么

​

遗留路径警告

• devtools_page/devtools_page.html
• options_ui/page.html
• background/page.html
• browser_action/default_popup.html
• page_action/default_popup.html
• side_panel/default_path.html
• sidebar_action/default_panel.html

​

最佳实践

• 让 manifest 路径相对于扩展的源/输出模型，仅在确实意指扩展输出根目录时才使用开头的 /。
• 使用带浏览器前缀的键，而不是为每个浏览器维护单独的 manifest 文件。
• 谨慎修改入口；在开发期新增/删除 manifest 脚本往往会改变重载语义。
• 把图标、JSON 资源和 content script 资源的校验作为持续集成（CI）的一部分，尽早发现路径回归。
• 不要把 manifest.json 放在 public/ 下。

​

下一步

• 在 dev 更新行为 中了解更新结果。
• 在 权限与主机权限 中设计最小权限访问。
• 了解 Extension.js 如何处理 浏览器特定的 manifest 字段。
• 在 页面重载与热模块替换（HMR） 中了解开发期的更新流程。

​

视频讲解