在 Webpack 的模块依赖图谱里，loader 的位置非常特殊。它不参与业务代码的最终打包，却在编译阶段承担翻译工作。既然是翻译器，就需要被 Webpack 调度和定位。一个常见的现象是：业务代码的别名或扩展名配置得好好的，但 loader 却报找不到模块。这背后通常是 resolveLoader 配置缺位。今天专门来看 resolveLoader.extensions 这个属性，理解它怎么影响 loader 的查找路径，以及如何在配置文件里精确控制它。
resolveLoader.extensions 的默认解析机制
resolveLoader 是 Webpack 提供的一个独立解析配置对象，专门服务于 loader 的路径解析。它与 resolve 配置并列存在，后者负责业务模块，前者负责 loader。如果在 resolveLoader 中不做任何扩展名配置，Webpack 内部会采用默认值。通常这份默认值包含 .js 和 .json。当你写下 loader: 'babel-loader' 时，Webpack 实际上会尝试 babel-loader.js、babel-loader.json，如果没有找到，才会去尝试不带扩展名的精确文件匹配，或者按照 resolveLoader.modules 指定的目录去查找。
很多开发者会把两者混为一谈，直接去修改 resolve.extensions，结果发现 loader 依然解析失败。因为 loader 的解析走的是独立的调度队列。这意味着如果你用 TypeScript 写了自定义 loader，或者项目里有 .jsx、.ts 结尾的 loader 文件，必须显式告诉 Webpack 往这个独立队列里添加扩展名。例如在 resolveLoader.extensions 中加入 .ts，才能让 Webpack 找到 my-loader.ts。需要注意的是，这个配置在 Webpack 不同版本中存在差异，较早的版本可能不会自动处理某些扩展名，因此显式声明总比依赖默认行为更稳妥。
下面是一个基础配置示例，用于给 loader 解析器增加 TypeScript 扩展名支持：
// webpack.config.js
module.exports = {
// ...
resolveLoader: {
extensions: ['.js', '.json', '.ts']
}
};
配置扩展名列表与自定义 loader 的匹配场景
假设团队维护了一批内部 loader，有些是用 .ts 编写的，有些是 .mjs。默认情况下只写 loader 名称会失败。可以扩展 extensions 数组，让它包含 .mjs、.ts 等。不过要注意顺序。数组从前到后的优先级意味着如果同名 loader 同时存在 .js 和 .ts 两个版本，Webpack 会优先命中写在最前面的扩展名。这个细节在多人协作项目中经常被忽略，导致本地开发和 CI 环境加载了不同的 loader 文件，最终产生难以追踪的编译差异。
扩展名列表并不是越长越好。每一个额外扩展名在解析失败时都会增加一次文件系统的探测请求。在大型仓库或 Windows 环境下，频繁的试探可能会拖慢冷启动速度。因此建议把最常用的扩展名放在前面，并避免加入不必要的后缀。如果是本地 loader，还可以结合 resolveLoader.modules 指定绝对路径，进一步缩短搜索时间。对于那些放在 node_modules 中的第三方 loader，extensions 的影响相对较小，因为包名通常直接指向目录，然后由包内的 main 字段决定入口文件。
下面的代码演示了一个结合 TypeScript loader 和自定义 loader 目录的完整配置：
const path = require('path');
module.exports = {
// ...
resolveLoader: {
modules: [path.resolve(__dirname, 'loaders'), 'node_modules'],
extensions: ['.ts', '.tsx', '.js', '.json']
},
module: {
rules: [
{
test: /\.js$/,
use: ['my-typescript-loader']
}
]
}
};
在这个配置中，my-typescript-loader 会先在 loaders 目录里寻找 my-typescript-loader.ts，因为 .ts 排在数组第一位。如果没有找到，再尝试 .tsx、.js 和 .json。如果最终都未命中，Webpack 会抛出模块未找到的错误，并在错误信息中列出所有尝试过的完整路径。
与 alias 及路径解析相关的常见误区
extensions 和 alias 的配合经常引发困惑。有时开发者配置了 resolveLoader.alias，指定 custom-loader 对应某个具体文件 path.join(__dirname, 'loaders/custom-loader.ts')。这时 extensions 还有用吗？答案是仍然有用，但作用范围变了。alias 提供的是精确映射，如果映射的是一个不带扩展名的路径，Webpack 依然会尝试使用 extensions 列表去补全它。因此即使设置了别名，最好也保证扩展名列表涵盖了目标文件的真实后缀，否则别名指向的路径依然可能解析失败。
另一个容易混淆的点是 resolveLoader.alias 与 resolve.alias 的区别。前者只对 loader 解析生效，后者只对业务模块生效。如果在 resolve.alias 中配置了 my-loader，然后在 module.rules 中直接使用 loader: 'my-loader'，Webpack 根本不会去查 resolve.alias，因为 loader 走的是 resolveLoader 分支。这种场景下必须把别名写在 resolveLoader.alias 中。理解这两个配置对象的隔离性，可以少走很多弯路。
想知道 Webpack 到底在找哪些路径吗？可以在启动脚本里加上 --stats-error-details，或者临时在配置中开启 infrastructureLogging 的 debug 级别。当 loader 解析报错时，错误信息里会输出 Webpack 尝试过的所有绝对路径。检查这份列表，就能直观看到 extensions 数组是否产生了正确的补全行为。这个方法在排查复杂多目录项目时非常有效，比盲目增加扩展名要可靠得多。
下面是一个包含 alias 和 extensions 的完整示例，注意数组顺序对解析优先级的影响：
const path = require('path');
module.exports = {
resolveLoader: {
alias: {
'virtual-loader': path.resolve(__dirname, 'loaders/virtual-loader')
},
extensions: ['.ts', '.js', '.json']
}
};
如果 virtual-loader 目录下同时存在 virtual-loader.ts 和 virtual-loader.js，那么由于 .ts 排在前面，Webpack 会选择 TypeScript 版本。这个小细节在多人协作或技术栈迁移时非常关键，能避免 loader 因为扩展名歧义而加载到错误文件。反过来，如果你的团队正在从 TypeScript 逐步迁移回 JavaScript，只需要调整 extensions 数组中 .js 和 .ts 的位置，就能在不改动业务代码的情况下切换 loader 实现。
resolveLoader.extensions 的配置看似简单，实际上和 Webpack 的解析器深度绑定。理解它的独立作用域、数组顺序以及和 alias 的协同方式，能解决大部分 loader 找不到或加载错误的问题。在项目配置文件中抽出几行来明确这份列表，往往比反复修改 loader 名称更有效。尤其是当项目结构复杂、本地 loader 数量增多时，提前规划好扩展名解析策略，可以显著降低后续维护成本。
WebpackresolveLoader.extensionsloader 解析修改时间：2026-10-04 17:27:32