WXT 模块：给框架加能力

模块是什么

WXT 提供了一套「模块系统」：让你在构建流程的不同阶段运行代码，从而修改构建过程。可以把它理解成「打包好的钩子包」——§30 讲过，钩子是散落在配置文件里的一段段逻辑；模块则是把相关逻辑封装成一个可安装、可复用的单元。

模块能做的事很多：改 manifest、生成文件、新增入口、注入自动导入，甚至给框架加全新的配置项。官方把框架集成（React/Vue）、图标生成、国际化、统计这些能力都做成了模块，安装即用。

安装已发布的模块

从 NPM 上找「wxt module」关键词，装上后在配置里声明：

npm i -D @wxt-dev/auto-icons

// wxt.config.ts
export default defineConfig({
  modules: ['@wxt-dev/auto-icons'],
});

真实项目通常一次挂多个模块。比如 mkext 模板的配置：

modules: [
  '@wxt-dev/module-react', // React 支持
  '@wxt-dev/auto-icons',   // 自动生成图标
  '@wxt-dev/i18n/module',  // 国际化
],

两类选项：构建期与运行时

模块的配置分两种：

1. 构建期选项：构建时用的配置，比如功能开关，写在 wxt.config.ts；
2. 运行时选项：运行时才读取的配置，比如回调函数，写在 <srcDir>/app.config.ts（如 §26 所述）。

TypeScript 下模块会增强 WXT 的类型。选项漏了或写错，编辑器直接报错，不用等构建失败才发现。

执行顺序

模块与钩子共用同一套执行顺序：

1. NPM 模块：按 modules 数组里的顺序；
2. 本地模块：modules/ 目录下的文件，按字母序；
3. 最后是 wxt.config.ts 里写的 hooks。

想调整顺序，给本地模块文件名加数字前缀即可（0.xxx.ts 先于 1.xxx.ts）。运行 wxt prepare --debug 能看到当前项目的完整顺序表：先是内置模块，再是你的本地模块，最后是配置文件里的 hooks。

写一个本地模块

自定义构建逻辑不一定要发布。放在项目根目录的 modules/ 文件夹下，任何模块文件都会被自动发现并加载，无需额外配置：

// modules/my-module.ts
import { defineWxtModule } from 'wxt/modules';

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

setup 在 wxt.config.ts 加载完后执行。参数 wxt 对象是模块的「工具箱」：

• wxt.hook(...)：挂进构建生命周期做修改；
• wxt.config：读取解析后的完整配置；
• wxt.logger：按 WXT 风格打印日志。

举一个改配置的例子——把输出目录改掉：

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

模块还可以用 configKey 给自己加构建期配置项，配合 declare module 'wxt' 的类型增强，用户就能在 wxt.config.ts 里写 myModule: {...}。运行时配置则通过增强 WxtAppConfig 类型，让 getAppConfig() 能读到模块自己的配置。写模块前，建议把 WxtHooks 接口里的钩子清单通读一遍，它们是模块能力的地图。

何时把钩子升级成模块

• 一个项目里钩子越写越多，wxt.config.ts 越来越乱 → 抽成本地模块；
• 同一套构建逻辑要在多个项目复用 → 发布成 NPM 模块，别人一行 modules: ['xxx'] 就能用；
• 想学习模块写法 → 读 @wxt-dev/auto-icons、@wxt-dev/i18n、module-react 等官方模块源码，它们是最好的教材。

小结

模块是钩子的封装与升级：安装、排序、写本地模块，三步即可上手。下一节看最常用的官方模块：自动图标。