WXT 模块系统完全指南：从构建流程扩展到自定义模块实战配方

前端开发工具构建工具插件系统【免费下载链接】wxt⚡ Next-gen Web Extension Framework项目地址https://gitcode.com/gh_mirrors/wx/wxt点击查看免费下载WXT 的模块系统Module System是一套允许你在构建流程的不同阶段注入代码、从而修改构建行为的扩展机制它是 WXT 生态中wxt-dev/auto-icons、wxt-dev/i18n等众多官方与社区能力的基础。本文将以 WXT 官方文档为主体结合仓库源码modules.ts、types.ts、wxt.ts 等深入讲解模块的安装、配置、执行顺序、编写方法以及九种高频实战配方读完你将能够为自己的扩展项目编写出类型完备、可发布的本地模块。什么是 WXT ModulesWXT 提供了一套模块系统让开发者可以在构建流程build process的不同步骤中运行代码来修改构建结果。模块可以做的事情包括修改已解析的配置如输出目录、Vite 配置在构建生命周期钩子hooks中拦截并改写 manifest、public 资源、entrypoint 列表向项目注入自动导入auto-imports、import 别名与类型声明生成运行时文件与运行时配置。从架构上看WXT 自身的若干能力自动导入 unimport、favicon 权限、Unicode 转义也是以内置模块形式实现的见 builtin-modules/index.ts它导出了unimport、faviconPermission、escapeUnicode三个内置模块与用户模块走完全相同的初始化路径。安装一个模块要使用 NPM 上发布的现成模块安装依赖后在wxt.config.ts的modules数组中声明即可export default defineConfig({ modules: [wxt-dev/auto-icons], });在 NPM 上搜索 wxt module 是发现已发布 WXT 模块的常用方式。模块的加载由 resolveWxtUserModules 完成modules数组中的每个条目会通过import.meta.resolve解析到 node_modules 中的真实路径并动态import要求模块必须存在 default export否则会抛出Module missing default export错误解析成功的模块会被标记为type: node_module。模块选项Build-time 与 RuntimeWXT 模块可能需要或允许自定义选项来改变行为选项分为两类Build-time构建期构建过程中使用的任何配置如功能开关Runtime运行期运行时访问的任何配置如回调函数。Build-time 选项放在wxt.config.ts中Runtime 选项放在app.config.ts文件中详见 运行时配置文档。每个模块需要哪些选项、放在哪里以该模块的文档为准。如果你使用 TypeScript模块会通过类型增强type augmentation扩展 WXT 的类型因此选项缺失或类型错误会在编译期直接报错。仓库中的示例模块 example.ts 展示了这一模式的完整写法定义ExampleModuleOptions接口再通过declare module wxt增强InlineConfig接口加入example?: ExampleModuleOptions字段。从源码看build-time 选项的解析在 resolve-config.ts 中完成所有已解析的用户模块按configKey从合并后的配置中提取对应字段形成moduleOptions映射并作为wxt.config的一部分传入 setup。而 runtime 选项则通过getAppConfig()读取其实现位于 app-config.ts内部直接返回全局的appConfig对象。模块的执行顺序模块与钩子按照相同的顺序执行。内置模块builtin modules先于用户模块user modules初始化wxt.config.ts中的hooks配置最后注册详见 wxt.ts 的 initWxtModules。更详细的钩子执行顺序说明可参考 Hooks 文档。两个细节值得注意本地模块放在modules/目录中的文件会先按文件名排序localModulePaths.sort()再依次加载以保证执行顺序的一致性见 resolve-config.ts当wxt.config.debug开启时WXT 会在初始化阶段把完整的钩子执行顺序打印到控制台内置模块名 → 用户模块相对路径 →wxt.config.ts hooks方便你排查执行顺序问题。编写你自己的模块如果项目需要自定义构建逻辑可以编写本地模块。一个最基本的 WXT 模块长这样import { defineWxtModule } from wxt/modules; export default defineWxtModule({ setup(wxt) { // Your module code here... }, });defineWxtModule定义在 modules.ts它接受一个模块对象或一个setup函数如果传入函数则会自动包装成{ setup }对象因此下面两种写法等价export default defineWxtModule((wxt) { // ... });模块自动发现将模块文件放在项目根目录的modules/目录下该目录中的任何模块文件都会被自动发现并加载无需额外配置rootDir/ modules/ my-module.ts ← loaded automatically源码中本地模块通过glob([*.[tj]s, */index.[tj]s], { cwd: modulesDir })发现支持目录下的index.ts形式随后用loadConfig加载要求文件必须有 default export否则抛出No config found for file错误见 resolve-config.ts。modulesDir默认是rootDir/modules也可以在wxt.config.ts中通过modulesDir配置项自定义。模块的源码结构从 types.ts 的 WxtModule 接口 可以看到一个模块对象支持的完整字段字段类型说明namestring模块名称本地模块缺省时以文件名作为 nameconfigKeystring用户在wxt.config.ts中传入选项所用的键名importsImport[]要添加到自动导入列表中的导入项hooksNestedHooksWxtHooks钩子对象会在setup之前注册setupWxtModuleSetupTOptions模块主体函数可注册钩子、调用模块 API其中WxtModuleSetup的类型签名为(wxt: Wxt, moduleOptions?: TOptions) void | Promisevoid也就是说setup支持异步。setup 函数与 wxt 对象每个模块的setup函数在wxt.config.ts加载完成后执行传入的wxt对象提供了编写模块所需的一切wxt.hook(...)挂接构建生命周期钩子并做出修改wxt.config获取项目wxt.config.ts解析后的完整配置含outDir、wxtDir、srcDir、alias、imports、plugins等wxt.logger向控制台输出日志wxt.hooks、wxt.pm包管理器、wxt.builder构建器、wxt.reloadConfig()等更多能力。Wxt接口的完整属性与函数列表可查阅 types.ts 中的接口定义。setup的调用发生在 initWxtModule如果模块声明了hooks字段会先注册钩子再调用setup(wxt, module.configKey ? wxt.config[module.configKey] : undefined)即第二个参数就是该模块configKey对应的 build-time 选项。模块辅助 API除了defineWxtModulemodules.ts 还导出了一组高频使用的辅助函数它们大多以注册一个 hook的方式实现避免你手写重复样板addEntrypoint(wxt, entrypoint)将一个 entrypoint 加入构建在entrypoints:resolved钩子中 push适合发布模块时配合wxt.builder.importEntrypoint提取 entrypoint 选项addPublicAssets(wxt, dir)把某个目录内的文件按 public 目录的方式复制进输出目录通过build:publicAssets钩子同名文件会被忽略如果模块要发布到 NPM官方建议预构建产物后用此函数复制而不是让用户重新打包以加快构建addViteConfig(wxt, viteConfig)合并额外的 Vite 配置到各个构建组wxt.config.ts中用户的 Vite 配置优先级更高内部使用vite.mergeConfigaddWxtPlugin(wxt, plugin)向项目添加运行时插件插件会在每个 entrypoint 的main函数执行前运行addImportPreset(wxt, preset)添加 unimport 预设内置预设、自定义预设或自动扫描预设到自动导入列表addAlias(wxt, alias, path)向 TSConfig paths 与打包器添加 import 别名若已存在同名 alias 会打印警告并跳过。Recipes 实战配方模块体系比较复杂需要深入理解 WXT 的代码与工作原理。学习的最佳方式就是看例子下面是官方文档给出的九个实战配方。更新解析后的配置import { defineWxtModule } from wxt/modules; export default defineWxtModule({ setup(wxt) { wxt.hook(config:resolved, () { wxt.config.outDir dist; }); }, });config:resolved在全部模块初始化完成后触发见 wxt.ts此时修改wxt.config会作用于整个构建过程。注意这里演示的是直接修改已解析配置对象的字段是最简单粗暴的干预方式。添加 Build-time 配置import { defineWxtModule } from wxt/modules; import wxt; export interface MyModuleOptions { // Add your build-time options here... } declare module wxt { export interface InlineConfig { // Add types for the myModule key in wxt.config.ts myModule: MyModuleOptions; } } export default defineWxtModuleMyModuleOptions({ configKey: myModule, // Build time config is available via the second argument of setup setup(wxt, options) { console.log(options); }, });要点configKey声明该模块在wxt.config.ts中的键名通过declare module wxt增强InlineConfig接口为myModule键提供类型提示defineWxtModuleMyModuleOptions让setup的第二个参数options获得正确的类型。用户随后就可以在配置中这样使用export default defineConfig({ modules: [my-module], myModule: { // 类型安全的自定义选项 }, });添加 Runtime 配置import { defineWxtModule } from wxt/modules; import wxt/utils/define-app-config; export interface MyModuleRuntimeOptions { // Add your runtime options here... } declare module wxt/utils/define-app-config { export interface WxtAppConfig { myModule: MyModuleRuntimeOptions; } }用户在你的模块对应的app.config.ts中配置运行时选项后运行时通过getAppConfig()读取const config getAppConfig(); console.log(config.myModule);getAppConfig定义在 app-config.ts同文件还提供了已废弃的useAppConfig别名。这种模式在生成 runtime 模块时非常有用——你可以在生成的代码里直接消费这些运行时配置。日志输出模块中添加控制台日志有两种正确方式使用wxt.logger输出 info、warn、error 级别信息安装obug包用createDebug输出可开关的调试日志。import { defineWxtModule } from wxt/modules; import { createDebug } from obug; const debug createDebug(my-module); export default defineWxtModule({ setup(wxt) { wxt.logger.info(Module loaded); debug(Debug details); }, });wxt.logger擅长输出与 WXT 其他日志风格一致的格式化、美观消息obug则便于开发者在需要时启用和过滤调试日志DEBUGmy-module wxt dev为 entrypoint 添加自定义选项模块可以通过增强 entrypoint 选项类型为 entrypoint 增加自定义配置这些配置在构建过程中可被访问import { defineWxtModule } from wxt/modules; import wxt; declare module wxt { export interface BackgroundEntrypointOptions { // Add custom options to the background entrypoint myCustomOption?: string; } } export default defineWxtModule({ setup(wxt) { wxt.hook(entrypoints:resolved, (_, entrypoints) { const background entrypoints.find((e) e.type background); if (background) { console.log(Custom option:, background.options.myCustomOption); } }); }, });用户随后可以在 entrypoint 中设置该选项export default defineBackground({ myCustomOption: custom value, main() { // ... }, });这种方式适用于所有 JS 和 HTML entrypoint。对 HTML entrypoint通过meta标签传递自定义选项html head meta namewxt.myHtmlOption contentcustom value / titlePopup/title /head body !-- ... -- /body /html生成输出文件import { defineWxtModule } from wxt/modules; export default defineWxtModule({ setup(wxt) { // Relative to the output directory 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], }); }); }, });这里同时展示了两个钩子的配合build:publicAssets中的assets数组支持两种条目——absoluteSrc复制现有文件与contents写入文本内容相关类型定义见 types.tsbuild:manifestGenerated则负责把生成文件注册为 web_accessible_resource使其可被页面访问。生成的文件可以在运行时加载const res await fetch(browser.runtime.getURL(/some-text.txt));如果你只是想复制一批现成文件官方推荐直接使用辅助函数addPublicAssets(wxt, dir)它会帮你完成build:publicAssets钩子的注册。添加自定义 entrypoints当entrypoints/目录下的既有文件被发现之后可以用entrypoints:found钩子添加自定义 entrypoint:::infoentrypoints:found钩子会在 entrypoint 列表执行校验之前触发。因此任何自定义 entrypoint 仍会接受重名检查并会在调试时被记录。 :::import { defineWxtModule } from wxt/modules; export default defineWxtModule({ setup(wxt) { wxt.hook(entrypoints:found, (_, entrypointInfos) { // Add your new entrypoint entrypointInfos.push({ name: my-custom-script, inputPath: path/to/custom-script.js, type: content-script, }); }); }, });如果你希望添加的 entrypoint 同时被 WXT 打包而不是指向已构建好的文件更推荐addEntrypoint(wxt, {...})辅助函数它会注册entrypoints:resolved钩子并在解析完成后追加 entrypoint。生成 runtime 模块在.wxt目录中创建文件、添加 import 别名、并为导出的变量添加自动导入import { defineWxtModule } from wxt/modules; import { resolve } from node:path; export default defineWxtModule({ imports: [ // Add auto-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(getAppConfig().analytics); export const { reportEvent, reportPageView } analytics; ; addAlias(wxt, #analytics, analyticsModulePath); wxt.hook(prepare:types, async (_, entries) { entries.push({ path: analyticsModulePath, text: analyticsModuleCode, }); }); }, });整个配方的三个环节在源码中都有对应实现imports字段由内置的 unimport 模块收集——在 unimport.ts 的config:resolved钩子中遍历wxt.config.builtinModules与wxt.config.userModules把每个模块声明的imports合并进wxt.config.imports.importsaddAlias内部注册config:resolved钩子把别名写入wxt.config.alias若已有同名 alias 则警告并跳过同时作用于 TSConfig paths 与打包器prepare:types把生成的.ts文件内容写入.wxt目录并纳入 TS 项目path默认相对于wxtDir解析。生成声明文件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 // Declare global types, perform type augmentation ; wxt.hook(prepare:types, async (_, entries) { entries.push({ path: my-module/types.d.ts, text: // Declare global types, perform type augmentation, etc , // IMPORTANT - without this line your declaration file will not be a part of the TS project: tsReference: true, }); }); }, });关键点是tsReference: true——没有这一行生成的声明文件不会被纳入 TS 项目类型增强将不生效。这与 unimport 内置模块生成types/imports.d.ts、types/imports-module.d.ts时的做法一致见 unimport.ts。另外prepare:types还会把发布在 NPM 的模块type: node_module以 TS reference 形式加入.wxt/wxt.d.ts以让它们的InlineConfig类型增强生效见 generate-wxt-dir.ts。参考示例模块动手编写模块之前建议通读 WXT 仓库中官方模块的完整实现它们是理解模块 API 与钩子配合方式的最佳范本packages/auto-icons自动生成各尺寸图标并写入 manifest其 index.ts 展示了configKey: autoIcons、setup 内解析选项默认值、通过build:manifestGenerated钩子覆写manifest.icons的完整流程packages/i18n国际化模块含module.ts与配套运行时工具packages/module-vue、packages/module-solid、packages/module-react、packages/module-svelte前端框架集成模块分别演示如何通过模块为不同框架注入 Vite 插件与自动导入预设。此外仓库自带的示例项目 wxt-demo/modules 中也有example.ts、i18n.ts、unocss.ts、auto-icons.ts等可直接运行调试的本地模块示例非常适合作为起步模板。模块系统的底层加载流程最后把模块的完整生命周期串起来看涉及 resolve-config.ts 与 wxt.ts解析配置resolveConfig解析wxt.config.ts调用resolveWxtUserModules加载两类用户模块——modules数组中声明的 NPM 模块标记为node_module和modules/目录下自动发现的本地模块标记为local且文件名会作为缺省 name提取选项按configKey从合并配置中提取各模块的 build-time 选项合并进wxt.config初始化模块initWxtModules先遍历builtinModules、再遍历userModules逐个调用initWxtModule——若模块声明了hooks字段先注册钩子随后调用setup(wxt, options)注册用户钩子wxt.config.ts中的hooks配置最后注册触发就绪依次触发ready与config:resolved钩子后续构建流程entrypoint 解析、manifest 生成、构建产物输出依次展开模块通过在这些钩子中注册的回调完成干预。理解这个流程后你就能准确把握选项何时就绪、钩子何时触发、修改配置应该挂在哪个钩子上从而写出稳定可靠的 WXT 模块。赞分享前端开发工具构建工具插件系统【免费下载链接】wxt⚡ Next-gen Web Extension Framework项目地址https://gitcode.com/gh_mirrors/wx/wxt点击查看免费下载相关推荐Merlin模块系统完全指南从标准模块到扩展模块的实战应用Merlin模块系统完全指南从标准模块到扩展模块的实战应用 Merlin是一个跨平台的渗透测试后渗透HTTP/2命令控制服务器和代理其强大的模块系统是核心功网络安全渗透测试10个实用技巧WXT钩子系统详解与扩展构建流程自定义指南10个实用技巧WXT钩子系统详解与扩展构建流程自定义指南 WXTNext gen Web Extension Framework作为一款现代浏览器扩展开发前端开发工具构建工具插件系统WXT模块系统完全指南构建可复用的浏览器扩展组件WXT模块系统完全指南构建可复用的浏览器扩展组件 WXT模块系统是现代浏览器扩展开发的核心利器 作为下一代Web扩展框架WXT通过模块化设计让开发者能前端开发工具构建工具插件系统上一篇对比Word与ElegantNote为什么LaTeX模板是学术笔记的最佳选择下一篇突破语言壁垒Python与JavaScript深度互操作实战解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考