如何编写Webpack插件在watch模式下动态更新resolve.modules与alias

问题背景 #

• 团队维护基于Webpack构建的大型monorepo项目，处理海量文件时采用全限定文件名模块导入规范：例如路径为/path/to/module/MyCoolModule.js的文件，可直接通过import MyCoolModule from 'MyCoolModule'导入，无需编写显式路径。
• 该能力通过Webpack初始化阶段递归扫描项目下所有.js文件与文件夹，将扫描结果传入resolve.modules与resolve.alias配置实现。
• 现有方案缺陷：常规watch模式下运行顺畅，但Webpack启动后新增文件/文件夹会出现解析失效——文件扫描仅在初始化阶段执行，启动后新增的文件无法被Webpack识别导入，直接导致编译失败，必须重启Webpack。当前项目单次Webpack重启耗时1-2分钟，工程师切换Git分支、拉取master分支更新时频繁重启会大量损耗开发时间、打断开发思路。
• 目标：编写自定义插件动态更新resolve.modules和resolve.alias，实现新增文件时无需重启Webpack。项目当前使用Webpack 4，同时兼容Webpack 5的实现方案。

核心问题解答 #

1. 可tap的钩子选型 #

要感知新文件/文件夹，分两类场景选钩子：

• 编译流程钩子：
  • Webpack 4 可tap顶层compiler的watchRun钩子，每次watch模式触发重编译前都会执行该钩子，能拿到本次变更的文件列表。注意Webpack默认不会监听未加入依赖图的目录，所以要感知全新文件夹新增，需要自己引入chokidar或者用原生fs.watch给项目根目录加监听。
  • Webpack 5 除了watchRun，还可以监听compilation钩子下的contextDependencies更新事件，对新增目录的原生感知能力更强，减少自定义监听的工作量。
• 解析流程钩子：如果要在模块导入解析时动态匹配路径，可tap resolver实例的resolve钩子，每一次模块导入解析都会触发这个钩子。

2. 插件配置位置 #

两个位置需要配合注册，不要只放单处：

• 要访问compiler级的watch、编译相关钩子，插件必须放在顶层plugins配置数组中，这部分插件在Webpack初始化最早阶段执行，能拿到完整的compiler实例，负责监听文件变更、维护路径映射表。
• 要介入resolve解析流程、访问resolver实例的钩子，需要在resolve.plugins数组中也注册同一个插件类的实例，负责在解析阶段读取最新的映射表返回正确路径。
• 注意：只放在resolve.plugins里拿不到compiler的watch相关钩子，没法感知文件变更；只放在顶层plugins里没法直接拦截模块解析流程，二者配合是成本最低的实现方式。

3. 让Webpack感知配置更新的实现方式 #

直接修改初始化时传入的resolve.modules/resolve.alias配置对象不会生效，因为Webpack启动时就会把传入的配置转换成内部resolver的缓存和解析规则，不会动态读取原始配置对象。两种可落地的方案：

方案1：直接修改resolver内部配置（侵入性较高）

• 顶层插件在afterPlugins钩子阶段可以拿到compiler挂载的resolver实例：Webpack 4 下从compiler.resolverFactory的缓存中取normal类型的resolver，Webpack 5 下通过compiler.resolverFactory.get('normal', resolveOptions)获取实例。
• resolver实例的运行时配置存在resolver.options对象上，直接修改其中的alias、modules字段，再调用resolver._resolveCache.clear()清空历史解析缓存，后续解析就会读取最新配置。
• 这个方案依赖Webpack resolver的内部属性，不同小版本可能有属性名变动，需要和当前项目使用的Webpack版本做适配。

方案2：自定义解析逻辑（兼容性更好，推荐）

不需要修改Webpack内部的resolve配置，逻辑完全自控：

1. 维护一份全局的「模块名-绝对路径」映射表，插件初始化时先做一次全量文件扫描生成初始映射。
2. 顶层注册的插件用chokidar监听项目目录的文件新增、删除、重命名事件，加300ms防抖避免Git切分支时大量文件变更触发频繁更新，实时维护映射表的正确性。
3. 在resolve.plugins中注册的插件tap resolver的resolve钩子，每次解析时先判断导入的模块名是否存在于映射表中，如果存在直接返回对应文件的绝对路径，手动把该路径加入Webpack的文件依赖列表后结束解析；如果不存在就交给后续默认解析逻辑处理。

• 这个方案不依赖Webpack的内部私有属性，Webpack 4和Webpack 5通用，而且直接查映射表的效率比Webpack默认遍历resolve.modules目录的效率高很多，更适配海量文件的monorepo场景。

踩坑提示：不要在每次文件变更时全量扫描所有文件，只需要增量处理新增/删除的单个文件路径更新映射表即可，否则大仓库下监听逻辑本身会带来明显的性能开销。

内容的提问来源于stack exchange，提问作者rkoval