跳转到主要内容
通过在 Extension.js 可以校验、重写并稳定输出的 manifest 字段中声明图标,保持扩展品牌与 action UI 的一致性。 Extension.js 会处理 manifest.json 中的图标路径,解析 public/相对路径,输出图标资源,并在开发期监视图标文件。

模板示例

action

action template screenshot 一个 action 扩展,在 manifest.json 中声明了工具栏图标。
仓库:extension-js/templates/action

图标能力

受支持的图标字段

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.
Chromium 只有在开启 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 时,提示也会说明:
在 Safari 构建中,提示会说明工具栏和应用图标各自使用什么:
浏览器前缀对这个键同样有效。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 输出路径。

下一步