WXT中文文档（机翻）

Appearance

表现型 ​

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

您扩展的 manifest.json 会输出到 .output/{target}/manifest.json 当运行 wxt build。

全局选项 ​

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

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 版本指定属性，它们在目标其他版本时将被移除。

名称 ​

Chrome 文档

如果未通过 manifest 配置项提供，则 manifest 的 name 属性默认为您的 package.json 的 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 中没有版本，则默认为 "0.0.0"。

图标 ​

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

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 权限将被添加以启用热 reload。
  • 当存在 sidepanel 入口点时：sidepanel 权限将被添加。
ts
export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
  },
});

主体权限 ​

Chrome 文档

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

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',
  },
});

见 国际化文档 以了解如何对您的扩展进行全面国际化的指导。

行动 ​

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

默认情况下，每当 action 被生成时，WXT 会将目标 MV2 的 browser_action 落地。

带有弹窗的行为 ​

要生成一个 manifest，其中在点击图标后 UI 出现，只需创建一个 Popup 入口点。如果您想在 MV2 中使用 page_action，请在 HTML 文档的 head 部分添加以下元标签：

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

不带弹窗的行为 ​

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

  1. 删除 Popup 入口点（如果存在）
  2. 在 manifest 中添加 action 关键字：
    ts
    export default defineConfig({
  manifest: {
    action: {},
  },
});

与带有弹窗的行为相同，WXT 会默认使用 browser_action 以目标 MV2。要使用 page_action 而非默认的 browser_action，请在 manifest 中添加：

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