WXT 模块

WXT 提供了一个“模块系统”，允许你在构建过程中不同阶段运行代码以修改它。

[[目录]]

添加模块

有两种方式可以将模块添加到你的项目中：

NPM：安装一个 NPM 包，例如 @wxt-dev/auto-icons 并将其添加到你的配置文件中：
typescript
```
// wxt.config.ts
export default defineConfig({
  modules: ['@wxt-dev/auto-icons'],
});
```
在 NPM 上搜索 "wxt 模块" 是找到已发布 WXT 模块的好方法。
本地：将文件添加到项目 modules/ 目录中：
```
<srcDir>/
  modules/
    my-module.ts
```
要了解如何编写自己的模块，请阅读编写模块文档。

模块选项

WXT 模块可能需要或允许设置自定义选项以改变其行为。有两种类型的选项：

构建时：任何用于构建过程的配置，如功能开关
运行时：任何在运行时访问的配置，如回调函数

构建时选项放置在你的 wxt.config.ts 中，而运行时选项放置在 app.config.ts 文件中。请参考每个模块的文档以了解所需的选项及其位置。

如果使用 TypeScript，则模块会增强 WXT 的类型，导致缺少或错误的选项返回类型错误。

执行顺序

模块按钩子执行的顺序加载。有关更多细节，请参阅钩子文档。

编写模块

以下是一个基本的 WXT 模块示例：

typescript

import { defineWxtModule } from 'wxt/modules';

export default defineWxtModule({
  setup(wxt) {
    // 你的模块代码在这里...
  },
});

每个模块的 setup 函数在加载 wxt.config.ts 文件后执行。wxt 对象提供了编写模块所需的 everything：

使用 wxt.hook(...) 钩子进入构建生命周期并进行更改
使用 wxt.config 获取项目 wxt.config.ts 文件中的 resolve 后的配置
使用 wxt.logger 在控制台输出消息
以及更多功能！

有关完整的 API 参考，请参阅 API 参考。

此外，确保阅读所有可用的钩子 - 它们是编写模块所必需的。

饼干

模块是复杂的，需要深入理解 WXT 的代码和它是如何工作的。最好的方法是通过示例来学习。

更新 resolve 配置

typescript

import { defineWxtModule } from 'wxt/modules';

export default defineWxtModule({
  setup(wxt) {
    wxt.hook('config:resolved', () => {
      wxt.config.outDir = 'dist';
    });
  },
});

添加构建时配置

typescript

import { defineWxtModule } from 'wxt/modules';
import 'wxt';

export interface MyModuleOptions {
  // 添加构建时选项在此处...
}
declare module 'wxt' {
  export interface InlineConfig {
    // 添加类型以应对 wxt.config.ts 中的 "myModule" 关键字
    myModule: MyModuleOptions;
  }
}

export default defineWxtModule<AnalyticModuleOptions>({
  configKey: 'myModule',

  // 构建时配置可通过 setup 函数的第二个参数访问
  setup(wxt, options) {
    console.log(options);
  },
});

添加运行时配置

typescript

import { defineWxtModule } from 'wxt/modules';
import 'wxt/sandbox';

export interface MyModuleRuntimeOptions {
  // 添加运行时选项在此处...
}
declare module 'wxt/sandbox' {
  export interface WxtAppConfig {
    myModule: MyModuleOptions;
  }
}

运行时配置在调用

typescript

const config = useAppConfig();
console.log(config.myModule);

此非常有用，尤其是在生成运行时代码。

生成输出文件

typescript

import { defineWxtModule } from 'wxt/modules';

export default defineWxtModule({
  setup(wxt) {
    // 相对于输出目录
    const generatedFilePath = 'some-file.txt';

    wxt.hook('build:publicAssets', (_, assets) => {
      assets.push({
        relativeDest: generatedFilePath,
        contents: 'some generated text',
      });
    });

    wxt.hook('build:manifestGenerated', (_, manifest) => {
      manifest.web_accessible_resources ??= [];
      manifest.web_accessible_resources.push({
        matches: ['*://*'],
        resources: [generatedFilePath],
      });
    });
  },
});

此文件随后可以在运行时加载：

typescript

const res = await fetch(browser.runtime.getURL('/some-text.txt'));

添加自定义入口

一旦发现现有文件夹下的所有入口文件已发现，可以使用 entrypoints:found 钩子添加自定义入口。

INFO

entrypoints:found 钩子在验证入口文件列表之前触发。因此，在任何自定义入口将仍然被检查以避免重复名称，并在调试时进行日志。

typescript

import { defineWxtModule } from 'wxt/modules';

export default defineWxtModule({
  setup(wxt) {
    wxt.hook('entrypoints:found', (_, entrypointInfos) => {
      // 添加新的自定义入口
      entrypointInfos.push({
        name: 'my-custom-script',
        inputPath: 'path/to/custom-script.js',
        type: 'content-script',
      });
    });
  },
});

生成运行时模块

创建一个文件在 .wxt，添加导入，并为导出的变量自动生成导出。

typescript

import { defineWxtModule } from 'wxt/modules';
import { resolve } from 'node:path';

export default defineWxtModule({
  imports: [
    // 添加自动生成的导入
    { from: '#analytics', name: 'analytics' },
    { from: '#analytics', name: 'reportEvent' },
    { from: '#analytics', name: 'reportPageView' },
  ],

  setup(wxt) {
    const analyticsModulePath = resolve(
      wxt.config.wxtDir,
      'analytics/index.ts',
    );
    const analyticsModuleCode = `
      import { createAnalytics } from 'some-module';

      export const analytics = createAnalytics(useAppConfig().analytics);
      export const { reportEvent, reportPageView } = analytics;
    `;

    addAlias(wxt, '#analytics', analyticsModulePath);

    wxt.hook('prepare:types', async (_, entries) => {
      entries.push({
        path: analyticsModulePath,
        text: analyticsModuleCode,
      });
    });
  },
});

生成声明文件

typescript

import { defineWxtModule } from 'wxt/modules';
import { resolve } from 'node:path';

export default defineWxtModule({
  setup(wxt) {
    const typesPath = resolve(wxt.config.wxtDir, 'my-module/types.d.ts');
    const typesCode = `
      // 宣布全局类型，执行类型增强
    `;

    wxt.hook('prepare:types', async (_, entries) => {
      entries.push({
        path: 'my-module/types.d.ts',
        text: `
          // 宣布全局类型，执行类型增强等
        `,
        // 重要 - 在此行无此字段会导致声明文件不作为 TS 项目的一部分：
        tsReference: true,
      });
    });
  },
});

示例模块

你应该还查看其他人的模块代码，以下是一些示例：

WXT 模块 ​

添加模块 ​

模块选项 ​

执行顺序 ​

编写模块 ​

饼干 ​

更新 resolve 配置 ​

添加构建时配置 ​

添加运行时配置 ​

生成输出文件 ​

添加自定义入口 ​

生成运行时模块 ​

生成声明文件 ​

示例模块 ​

WXT 模块

添加模块

模块选项

执行顺序

编写模块

饼干

更新 resolve 配置

添加构建时配置

添加运行时配置

生成输出文件

添加自定义入口

生成运行时模块

生成声明文件

示例模块