WXT浏览器插件开发中文教程(4)----WXT配置详解之manifest清单

前言

大家好，我是倔强青铜三 。是一名热情的软件工程师，我热衷于分享和传播IT技术，致力于通过我的知识和技能推动技术交流与创新，欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

清单 ​

=======================

在 WXT 中，您的源代码中没有 manifest.json 文件。相反，WXT 从多个来源生成清单：

• 全局选项 [在您的 wxt.config.ts 文件中定义](#在您的 wxt.config.ts 文件中定义 "#global-options")
• 入口特定选项 在您的入口点中定义
• 添加到项目的 WXT 模块可以修改您的清单
• 在项目中定义的 钩子可以修改清单

运行 wxt build 时，扩展的 manifest.json 将输出到 .output/{target}/manifest.json。

全局选项 ​

要向清单中添加属性，请在 wxt.config.ts 中使用 manifest 配置：

export default defineConfig({
  manifest: {
    // 在此处进行手动更改
  },
});

您还可以将清单定义为一个函数，并使用 JavaScript 根据目标浏览器、模式等生成清单。

export default defineConfig({
  manifest: ({ browser, manifestVersion, mode, command }) => {
    return {
      // ...
    };
  },
});

MV2 和 MV3 兼容性 [​](#MV2 和 MV3 兼容性 "#mv2-and-mv3-compatibility")

在向清单添加属性时，尽可能使用 MV3 格式。当针对 MV2 时，WXT 会自动将这些属性转换为 MV2 格式。

例如，对于以下配置：

export default defineConfig({
  manifest: {
    action: {
      default_title: 'Some Title',
    },
    web_accessible_resources: [
      {
        matches: ['*://*.google.com/*'],
        resources: ['icon/*.png'],
      },
    ],
  },
});

WXT 将生成以下清单：

MV2版本的清单

{
  "manifest_version": 2,
  // ...
  "browser_action": {
    "default_title": "Some Title"
  },
  "web_accessible_resources": ["icon/*.png"]
}

MV3版本的清单

{
  "manifest_version": 3,
  // ...
  "action": {
    "default_title": "Some Title"
  },
  "web_accessible_resources": [
    {
      "matches": ["*://*.google.com/*"],
      "resources": ["icon/*.png"]
    }
  ]
}

您还可以指定特定于单个清单版本的属性，这些属性将在针对其他清单版本时被移除。

名称 ​

Chrome 文档

如果未通过 manifest 配置提供名称，清单的 name 属性默认为 package.json 的 name 属性。

版本和版本名称 ​

Chrome 文档

扩展的 version 和 version_name 基于 package.json 的 version。

• version_name 是列出的确切字符串
• version 是清理后的字符串，去除了任何无效的后缀

示例：

// package.json
{
  "version": "1.3.0-alpha2"
}

// .output/<target>/manifest.json
{
  "version": "1.3.0",
  "version_name": "1.3.0-alpha2"
}

如果 package.json 中没有版本，它默认为 "0.0.0"。

图标 ​

WXT 通过查看 public/ 目录中的文件自动发现扩展的图标：

public/
├─ icon-16.png
├─ icon-24.png
├─ icon-48.png
├─ icon-96.png
└─ icon-128.png

具体来说，图标必须匹配以下正则表达式才能被发现：

const iconRegex = [
  /^icon-([0-9]+)\.png$/,                 // icon-16.png
  /^icon-([0-9]+)x[0-9]+\.png$/,          // icon-16x16.png
  /^icon@([0-9]+)w\.png$/,                // icon@16w.png
  /^icon@([0-9]+)h\.png$/,                // icon@16h.png
  /^icon@([0-9]+)\.png$/,                 // icon@16.png
  /^icons?[/\\]([0-9]+)\.png$/,          // icon/16.png | icons/16.png
  /^icons?[/\\]([0-9]+)x[0-9]+\.png$/,   // icon/16x16.png | icons/16x16.png
];

如果您不喜欢这些文件名，或者正在迁移到 WXT 而不想重命名文件，可以在清单中手动指定 icon：

export default defineConfig({
  manifest: {
    icons: {
      16: '/extension-icon-16.png',
      24: '/extension-icon-24.png',
      48: '/extension-icon-48.png',
      96: '/extension-icon-96.png',
      128: '/extension-icon-128.png',
    },
  },
});

或者，您可以使用 @wxt-dev/auto-icons 让 WXT 生成所需尺寸的图标。

权限 ​

Chrome 文档

大多数情况下，您需要手动向清单中添加权限。只有在少数特定情况下会自动添加权限：

• 在开发过程中：会添加 tabs 和 scripting 权限以启用热重载。
• 当存在 sidepanel 入口点时：会添加 sidepanel 权限。

export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
  },
});

主机权限 ​

Chrome 文档

export default defineConfig({
  manifest: {
    host_permissions: ['https://www.google.com/  *'],
  },
});

警告

如果您使用主机权限并同时针对 MV2 和 MV3，请确保仅包含每个版本所需的主机权限：

export default defineConfig({
  manifest: ({ manifestVersion }) => ({
    host_permissions: manifestVersion === 2 ? [...] : [...],
  }),
});

默认语言 ​

export default defineConfig({
  manifest: {
    name: '__MSG_extName__',
    description: '__MSG_extDescription__',
    default_locale: 'en',
  },
});

有关国际化扩展的完整指南，请参阅 I18n 文档。

Action ​

在 MV2 中，您有两个选择：browser_action 和 page_action。在 MV3 中，它们合并为一个 action API。

默认情况下，每当生成 action 时，WXT 在针对 MV2 时会回退到 browser_action。

带有弹出窗口的Action ​

要生成在点击图标后显示 UI 的清单，只需创建一个 弹出窗口入口点。如果您想在 MV2 中使用 page_action，请在 HTML 文档的头部添加以下元标签：

<meta name="manifest.type" content="page_action" />

不带弹出窗口的Action ​

如果您想使用 activeTab 权限或 browser.action.onClicked 事件，但不想显示弹出窗口：

1. 如果存在 弹出窗口入口点，请将其删除

2. 在清单中添加 action 键：

   export default defineConfig({
     manifest: {
       action: {},
     },
   });

与带弹出窗口的Action相同，WXT 会回退到使用 MV2 的 browser_action。如果想改用 page_action，也添加该键：

export default defineConfig({
  manifest: {
    action: {},
    page_action: {},
  },
});

最后感谢阅读！欢迎关注我，微信公众号 ：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！