构建钩子：在构建流程里插一手

WXT 的构建是一条流水线：解析配置、发现入口、生成清单、打包产物。钩子（hooks）就是在这条流水线上预留的插槽，让你在特定节点插入自己的代码，改变构建结果。

在 wxt.config.ts 里加钩子

最轻量的挂载方式，是直接在配置文件的 hooks 字段里写。下面这个钩子会在清单写进输出目录之前，给开发构建的扩展名加个 (DEV) 后缀：

export default defineConfig({
  hooks: {
    'build:manifestGenerated': (wxt, manifest) => {
      if (wxt.config.mode === 'development') {
        manifest.name += ' (DEV)';
      }
    },
  },
});

build:manifestGenerated 就是「清单已生成」这个节点的钩子名。有了它，同一个扩展在开发版和生产版里名字不同，一眼就能分辨装的是哪个版本。

钩子的参数怎么用

大多数钩子的第一个参数是 wxt 对象，里面装着解析后的完整配置和当前构建的信息，比如上例的 wxt.config.mode。后面的参数是构建系统的各个部件，直接改引用就能生效——manifest 是对象，改它的属性就是在改最终产物。

WXT 提供哪些钩子？完整的清单在官方 API 参考的 WxtHooks 接口里，常见的有：

• build:manifestGenerated：清单生成后，写入前
• build:publicAssets：公共资源收集后
• entrypoints:found：入口文件发现后（模块里常用）
• prepare:tsconfig：tsconfig 写出前（§29 用过）
• config:resolved：配置解析完成后

具体每个钩子的参数与时机，以 API 参考为准。

执行顺序：谁先谁后

钩子可以定义在多个地方，顺序会影响结果。WXT 的执行顺序固定为：

1. modules 配置里列出的 NPM 模块，按数组顺序
2. 项目 modules/ 目录下的本地模块，按文件名排序
3. wxt.config.ts 里的 hooks

想看自己项目的实际顺序，跑 wxt prepare --debug，然后搜索 Hook execution order：

⚙ Hook execution order:
⚙   1. wxt:built-in:unimport
⚙   2. src/modules/auto-icons.ts
⚙   3. src/modules/example.ts
⚙   4. src/modules/i18n.ts
⚙   5. wxt.config.ts > hooks

调整执行顺序

想让某个本地模块先跑，给它加数字前缀，数字小的先加载：

📁 modules/
   📄 0.my-module.ts
   📄 1.another-module.ts

这一招还能解决「NPM 模块想在本地模块之后跑」的需求：把 NPM 模块重新导出成一个带数字前缀的本地模块即可：

// modules/2.i18n.ts
export { default } from '@wxt-dev/i18n/module';

这样它排在 1.another-module.ts 后面，但仍在 wxt.config.ts 的钩子之前。

钩子太多怎么办：升级成模块

在配置文件里写一两个一次性钩子，简单直接。但钩子多了，配置文件会变得臃肿，也不好测试。这时候就该把它们抽成 WXT 模块（§31）：

import { defineWxtModule } from 'wxt/modules';

export default defineWxtModule({
  setup(wxt) {
    wxt.hook('build:manifestGenerated', (_, manifest) => {
      // 你的逻辑
    });
  },
});

模块本质上就是「钩子的集合」：setup 里用 wxt.hook(...) 挂载任意数量的钩子，还能用 wxt.config、wxt.logger 等能力。放进 modules/ 目录自动加载，不用改配置。判断标准很简单：钩子数量超过两三个，或者逻辑需要复用、测试，就升级成模块。

小结

• hooks 是构建流程里的插槽，build:manifestGenerated 等钩子按名字注册。
• 执行顺序：NPM 模块 → 本地模块 → config 里的 hooks，数字前缀可微调。
• 逻辑复杂到要传配置时，把钩子升级成模块（§31）。