WXT 中文文档

Appearance

Manifest ​

在 WXT 中，源代码里没有 manifest.json 文件。WXT 会从多个来源生成 manifest：

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

全局选项 ​

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

ts
export default defineConfig({
  manifest: {
    // 在此处添加手动更改
  },
});

你也可以将 manifest 定义为函数，使用 JS 根据目标浏览器、模式等来生成它。

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

MV2 和 MV3 兼容性 ​

向 manifest 添加属性时，尽可能使用 MV3 格式定义属性。当目标为 MV2 时，WXT 会自动将这些属性转换为 MV2 格式。

例如，对于以下配置：

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

WXT 将生成以下 manifest：

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

你也可以指定仅适用于单个 manifest 版本的属性，当目标为另一个 manifest 版本时，这些属性将被自动移除。

Name ​

Chrome 文档

如果未通过 manifest 配置提供，manifest 的 name 属性默认使用 package.json 中的 name 属性。

Version 和 Version Name ​

Chrome 文档

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

  • version_name 是列出的完整字符串
  • version 是清理后的字符串，移除了所有无效后缀

示例：

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

如果 package.json 中没有 version，则默认为 "0.0.0"。

图标 ​

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

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

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

ts
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 且不想重命名文件，可以在 manifest 中手动指定 icon：

ts
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 文档

大多数情况下，你需要手动将权限添加到 manifest 中。只有在少数特定情况下会自动添加权限：

  • 开发期间：会添加 tabs 和 scripting 权限以启用热重载。
  • 当存在 sidepanel 入口点时：会添加 sidepanel 权限。
ts
export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
  },
});

主机权限 ​

Chrome 文档

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

WARNING

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

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

默认语言 ​

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

参阅 I18n 文档 获取完整的扩展国际化指南。

Actions ​

在 MV2 中，你有两个选项：browser_action 和 page_action。在 MV3 中，它们被合并为单个 action API。

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

带弹出窗口的 Action ​

要生成一个点击图标后显示 UI 的 manifest，只需创建一个 Popup 入口点。如果你想在 MV2 中使用 page_action，请在 HTML 文档的 head 中添加以下 meta 标签：

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

不带弹出窗口的 Action ​

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

  1. 删除 Popup 入口点（如果存在）

  2. 在 manifest 中添加 action 键：

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

与带弹出窗口的 action 相同，WXT 在 MV2 中会回退为使用 browser_action。要改用 page_action，请同时添加该键：

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