manifest.json 中的图标路径,解析 public/相对路径,输出图标资源,并在开发期监视图标文件。
模板示例
action

manifest.json 中声明了工具栏图标。
图标能力
受支持的图标字段
Chromium 不接受
.svg(或 .webp)作为 icons 与 action 图标。把这些字段指向
SVG 的 manifest 能在 Firefox 中加载,但在 Chrome、Edge、Brave 和 Opera 中会失败。
面向所有 Chromium 目标请提供 PNG 文件。sidebar_action 与
browser_action.theme_icons 是 Firefox 字段,而且 sidebar_action.default_icon
对 .svg 的支持在那里也只是部分的(*)。manifest.json 中的图标声明示例
图标变体
icon_variants 为每种配色方案声明一组图标。Extension.js 会读取顶层的这个键,以及 action、browser_action 和 page_action 之下的这个键。
icons 一样被输出和检查:
- 每个变体文件都输出在它的源位置,它在 manifest 中的路径遵循与
icons相同的规则。 - 缺少变体文件时,构建会以图标错误停止,错误里会写出这个键:
Can't find an icon file listed in icon_variants.
ExtensionIconVariants 标志时才读取 icon_variants,Firefox 目前还不读取这个键。对于这些目标,构建会保留你的 manifest 中声明的 icons 和 action 的 default_icon。
如果 manifest 中没有它们,构建会先用不带 color_schemes 的变体组来填充,其次用浅色组。Chromium 只接受 PNG 尺寸,Firefox 还可以使用 any 的 SVG。
Safari 会在工具栏上读取 icon_variants,写在顶层或 action 下都可以,并且优先于 icons。在 Safari 27 上实测,它始终绘制浅色组,在深色外观下也不会切换到深色组。Apple 的应用转换器不读取这个键,只用 icons 来生成应用图标。所以 Safari 构建会得到同样的后备处理:
- 如果 manifest 中有
icons和 action 的default_icon,构建会保留它们。 - 如果 manifest 中没有它们,构建会先用不带
color_schemes的变体组来填充,其次用浅色组。 - 构建优先使用 PNG 尺寸,只有在没有任何组提供 PNG 时才使用 SVG。
icon_variants本身会留在 Safari 的输出里,所以 Apple 的转换器仍然会把这个键列为不支持。
icons 时,提示也会说明:
chromium:icon_variants 或 firefox:icon_variants 下的列表只会在对应浏览器的构建中输出它的文件。参见浏览器特定的 manifest 字段。
从 SVG 生成各尺寸 PNG
把 SVG 保留为设计源文件,导出所有浏览器都接受的 PNG 尺寸。下面这条命令使用 librsvg 提供的rsvg-convert(macOS 上 brew install librsvg,Debian 与 Ubuntu 上 apt install librsvg2-bin):
icons 与 action.default_icon 指向这些 PNG 文件。
输出路径
典型的图标输出:icons/ 文件夹里。声明为 images/icon.png 的图标会输出在
images/icon.png,输出的 manifest 也仍然指向同一个路径。
路径行为
- Extension.js 会从 manifest 所在目录解析相对图标路径。
- 以
/开头的路径和public/...会按扩展 public-root 语义解析。 - Extension.js 可以监视 public 文件夹中的资源,而不必通过图标特性本身重新输出它们。
- 由动态导入的模块设置的图标,会发布在加载该模块的 worker 或页面旁边。见运行时加载的文件。
开发期行为
- 修改已存在的图标文件会触发重新编译。
- 当 manifest 的修改改变了图标引用时,正在运行的
extension dev会话会自行重启编译器。 - 缺失必需的图标文件会产生构建错误(某些可选的图标组只会产生警告)。
最佳实践
- 显式声明 manifest 图标字段,而不是依赖偶发的资源导入。
- 提供多种图标尺寸(
16、32、48、128),让 UI 在各浏览器表面更清晰。 - 保持图标文件名稳定,减少开发期对 manifest 的扰动。
- 有意地使用 public-root 路径,并测试由此产生的 manifest 输出路径。
下一步
- 继续阅读 web-accessible 资源。
- 进一步了解 特殊文件夹。

