manifest.json 逐字段详解（MV3 必备项与易错项）

manifest.json 是扩展的身份证兼操作手册：浏览器靠它认识你的扩展，也靠它划定你的权限边界。这个文件是声明式的，写错就是硬错误——不是功能异常，而是整个扩展拒绝加载。这一篇按「必备、常用、易错」三个层次过一遍 MV3 的字段。

必备字段

平台强制要求三个字段，缺一不可：

{
  "manifest_version": 3,
  "name": "我的扩展",
  "version": "1.0.0"
}

manifest_version 只能是 3。name 最长 75 字符，会出现在安装对话框和 chrome://extensions 页面。version 是 1 到 4 段的点分非负整数，如 1.2.10，每段不超过 16 位；它决定商店更新逻辑，发版只增不减。

商店另有两条硬要求：description（最长 132 字符）和 icons。图标建议 16、48、128 三档 PNG：

{
  "manifest_version": 3,
  "name": "我的扩展",
  "version": "1.0.0",
  "description": "一句话说清楚它是干什么的",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

常用字段速查

注意 default_locale 的规则是双向的：有 _locales 目录则必须写，没有则禁止写——这是 JSON 声明式文件特有的「写了也错」类目。

最容易踩的坑

坑一：JSON 语法。manifest 不允许注释、不允许尾逗号。编辑器的 JSON 校验务必开着，HBuilderX 等工具的语法检查能拦下大半低级错误，见 HBuilderX 效率技巧。

坑二：relative path 写成绝对路径。所有文件引用都是相对于扩展根目录的相对路径，写成 /images/icon.png 带前导斜杠在部分字段会失效，规范写法是 images/icon.png。

坑三：background 写法沿袭 MV2。MV2 的 "background": { "scripts": [...] } 在 MV3 已不存在，必须是：

"background": { "service_worker": "background.js" }

坑四：权限想当然。以为 tabs 权限才能用 chrome.tabs——实际上多数 tabs 方法无需任何权限，tabs 权限只是解锁读取 url、title、favIconUrl 这四个敏感属性。权限与警告的对应关系，官方有专门的 permissions-list 可查，链接见文末。

坑五：web_accessible_resources 沿用 MV2 写法。MV3 从字符串数组改成了对象数组，且必须声明资源和暴露范围的映射：

"web_accessible_resources": [
  {
    "resources": ["inject.js"],
    "matches": ["https://example.com/*"]
  }
]

一个功能完整的 MV3 manifest 样例

把常用字段拼在一起，作为项目模板：

{
  "manifest_version": 3,
  "name": "划词收藏夹",
  "version": "0.3.0",
  "description": "选中网页文字一键收藏并同步",
  "icons": { "16": "icons/icon-16.png", "128": "icons/icon-128.png" },
  "permissions": ["activeTab", "storage", "contextMenus"],
  "host_permissions": ["https://api.myservice.com/*"],
  "background": { "service_worker": "background.js" },
  "action": { "default_popup": "popup.html", "default_title": "划词收藏" },
  "content_scripts": [
    { "matches": ["https://*.news.com/*"], "js": ["content.js"], "run_at": "document_idle" }
  ],
  "commands": {
    "save-selection": {
      "suggested_key": { "default": "Ctrl+Shift+S" },
      "description": "收藏当前选中文字"
    }
  }
}

字段的官方权威来源

字段全集与每个字段的精确语义，以官方 Manifest 页为准：https://developer.chrome.com/docs/extensions/reference/manifest 。权限列表在 https://developer.chrome.com/docs/extensions/reference/permissions-list 。本书后续章节会逐个深入 action、background、content_scripts、commands 这些大字段。

match 模式是 host_permissions 与 content_scripts 的公共语法，写法细节容易错，正则匹配写法可参考本站《正则表达式从入门到精通》：正则实战。

字段的继承与迁移

如果你在维护一个 MV2 老扩展，manifest 迁移有固定对照关系，官方 migrate 文档有完整清单，这里列最常改的几项：

MV2 的 manifest 文档仍在官方站点保留（developer.chrome.com/docs/extensions/mv2/manifest），核对旧字段时有用，但新项目一律从 MV3 文档出发。

manifest 的调试与校验

声明式文件的排错有自己的特点：错误发生在「加载时」而不是「运行时」，因此要用加载时的反馈来查。三层校验由浅入深：

1. 编辑器层：JSON 语法校验，拦住逗号、注释、引号问题，工程化项目可加 schema 校验（社区有 manifest 的 JSON Schema，编辑器装插件后 manifest 能自动提示字段）；
2. 浏览器层：chrome://extensions 的「错误」按钮，报错信息精确到字段名，比如 unrecognized key 或 invalid value；
3. 行为层：扩展加载成功但某功能不工作，先怀疑权限与路径——console 里会出现「cannot access」类报错，反查 manifest 对应声明。

「加载成功但功能静默失效」是声明式文件最迷惑人的地方：拼错一个字段名（如 command 写成 commands 的子结构错位）浏览器可能只是忽略它而不报错。所以养成习惯：改完 manifest 重载扩展后，到错误按钮确认零报错，再测功能。

结构化的 manifest 管理

manifest 会随功能增长越来越大，两个管理建议。一是加注释的需求用「生成式」方案：用脚本从带注释的源文件（如 JSON5 或 JS 配置）生成纯 JSON，构建时顺带做版本号注入；二是至少把 manifest 纳入 code review 的必看文件——它是全项目唯一「错一行全盘拒绝」的文件，合并冲突要人工逐字段核对，不能随手 accept。

字段全集与每个字段的精确语义，以官方 Manifest 页为准：https://developer.chrome.com/docs/extensions/reference/manifest 。match 模式是 host_permissions 与 content_scripts 的公共语法，写法细节容易错，正则匹配写法可参考本站《正则表达式从入门到精通》：正则实战。

本章由 WorkBuddy 原创整理，API 行为依据 Chrome 扩展官方文档（Manifest V3）。