清单基础字段

每个浏览器扩展都必须有一份 manifest.json。它是整个扩展的身份证，也是浏览器加载扩展时第一个读取的文件。浏览器靠这份清单决定：扩展叫什么、版本多少、要哪些权限、后台脚本在哪、弹出页面又是哪个。

前面几章你已经跑通过 Hello World，那里面就藏着一份最小清单。这一节我们把最基础、也最常被忽略的四个字段拆开讲清楚：name、version、description、manifest_version，再加上 icons 图标约定。把这几项写对，扩展才能被浏览器正常识别、上架和展示。

6-1 manifest_version 是第一位

manifest_version 告诉浏览器你用的是哪一代扩展平台。本教程全程只讲 Manifest V3，所以这个字段永远写 3，而且是数字类型，不是字符串。

{
  "manifest_version": 3
}

这里有个新手坑：3 不要加引号。写成 "3" 在旧习惯里常见，但 V3 规范里它就是数字。浏览器读到非 3 的值会直接拒绝加载。

manifest_version 通常会放在清单最上面一行。它不依赖任何其它字段，但其它几乎所有东西都建立在它之上。

6-2 name 扩展的名字

name 是扩展的显示名称，必填，类型为字符串。它会出现在三处地方：浏览器扩展管理页面、Chrome Web Store 的详情页、以及工具栏上鼠标悬停时（如果你没单独设标题）。

填写时有两条硬规则：

1. 最长 75 个字符。超过会被截断或上架时被拒。
2. 别在名字里蹭商标。Chrome、Google 这类品牌词不是绝对禁用，但一旦造成”官方出品”的误导，审核就会卡住，所以能避开就避开。

{
  "manifest_version": 3,
  "name": "我的第一个标签整理器"
}

名字建议直白说清扩展是干什么的。用户一眼扫过去，靠名字判断要不要点开。像”一键截图工具""网页划词翻译”这种就比”小助手”清楚得多。

6-3 version 版本号怎么写

version 是扩展的版本标识，必填，类型是字符串。它的作用是让浏览器和商店区分”这是第几版”。每次你更新扩展重新上架，都必须把版本号调高，否则商店会拒绝覆盖旧包。

版本号的格式是用点分隔的 1 到 4 段数字：

{
  "version": "1.0.0"
}

也可以是 "1.0"、"1.0.0.0"，最多四段。每段只能是 0 到 65535 之间的非负整数，而且不能有前导零；另外各段也不能全为 0，"0"、"0.0.0.0" 这类写法不合法（"0.1.0.0" 可以）。下面这些写法都是错的：

• "1.0.0.0.0"：超过四段。
• "01.2.3"：第一段有前导零。
• "1.2.3 beta"：带了非数字字符。
• "0.0.0.0"：各段全为 0。

版本号本身不强迫你用”语义化版本”，但业界普遍按”主版本.次版本.修订号”来理解。我的建议是这样分：

• 第一段（主版本）：大改、不兼容旧版的更新时加。
• 第二段（次版本）：加了新功能但还能兼容时加。
• 第三段（修订号）：修 bug、小调整时加。

举例：你发第一版是 "1.0.0"，加了个翻译功能就升到 "1.1.0"，后来修了个弹出页错位就升到 "1.1.1"。

6-4 description 一句话说明

description 是可填但强烈建议填的字段，类型字符串，最多 132 个字符。它会出现在扩展管理页和商店列表里，紧挨着名字，用来补充”这个扩展到底能帮你做什么”。

{
  "manifest_version": 3,
  "name": "我的第一个标签整理器",
  "version": "1.0.0",
  "description": "一键把杂乱的标签页按域名分组，告别浏览器顶部长长一排。"
}

写描述时注意两点：一是说人话，讲清楚解决什么具体问题；二是别堆关键词。商店审核对”关键词堆砌”很敏感，老老实实写功能反而更容易过。

6-5 icons 图标尺寸约定

icons 字段用来声明扩展在不同地方用的图标文件。它是个对象，键是像素尺寸，值是图片路径。浏览器会在工具栏管理、商店、安装弹窗等不同场景自动挑最合适的尺寸。

{
  "manifest_version": 3,
  "name": "我的第一个标签整理器",
  "version": "1.0.0",
  "description": "一键把杂乱的标签页按域名分组。",
  "icons": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

尺寸约定有一条是硬性的：128×128 必须有。商店上架和扩展管理页都会用到这张图，缺了它审核直接不过。其余尺寸不是强制，但建议至少把 16、32、48、128 都备齐：

• 16：扩展管理页列表里的小图标、Windows 任务栏。
• 32：Windows 上某些高分屏场景。
• 48：扩展管理页的默认展示。
• 128：商店详情页、安装确认框，强制需要。

图标文件建议用 PNG 格式——它无损且支持透明，缩放后边缘干净。JPG、BMP、GIF、ICO 这些栅格格式也能用，唯独 SVG 和 WebP 不行，浏览器不认。把图放进扩展目录下的 icons/ 文件夹是约定俗成的做法，路径写相对清单的位置即可。

关于图标设计，我有个实在建议：别用纯文字当图标，缩到 16 像素就糊成一团。用简单图形加高对比颜色，远看能认出来最重要。

6-6 把它们拼成一份完整开头

把上面五个字段合起来，就是一份合规清单的开头。它已经能被浏览器识别并加载，即便还没写任何功能脚本。

{
  "manifest_version": 3,
  "name": "我的第一个标签整理器",
  "version": "1.0.0",
  "description": "一键把杂乱的标签页按域名分组，告别浏览器顶部长长一排。",
  "icons": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

到这里，四个基础字段加图标约定就讲完了。这一份虽然还做不了任何事，但它是后面所有功能挂载的地基。下一节我们加 action，让工具栏真正出现一个能点的按钮；再往后加 background，给扩展一个后台大脑。

基础字段看着简单，却是每个扩展的起点。把 manifest_version 写对、name 和 version 符合规范、icons 备齐 128，这份清单就立得住了。后面章节加的权限、脚本、页面，全都是在这份地基上继续盖楼。