Webpack 5 对 loader 体系进行了多项调整，其中影响面最大的是内置 Asset Modules 替代传统文件类 loader，以及 loader 开发接口的规范化。升级后，开发者不必再安装 file-loader、url-loader、raw-loader，直接通过 module.rules 中的 type 字段即可处理静态资源。这一变化减少了依赖数量，也避免了多个 loader 之间解析顺序冲突的问题。接下来围绕资源模块、API 调整和异步缓存机制展开说明。
一、Asset Modules：内置资源模块取代文件类 Loader
Webpack 5 引入四种资源模块类型，分别对应旧版常用 loader 的功能。asset/resource 会将文件输出到输出目录并返回 URL，功能与 file-loader 一致；asset/inline 将资源转为 data URI 内联到产物中，等同于 url-loader 的 limit 设置为无穷大；asset/source 直接导出文件源码，替代 raw-loader；而 asset 则提供自动选择能力，根据文件大小在 resource 和 inline 之间切换，类似 url-loader 的 limit 机制。使用这些内置类型后，不需要再额外安装 loader 包，配置也更简洁。
以处理图片和文本为例，webpack.config.js 可以这样写：
const path = require('path');
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js',
},
module: {
rules: [
{
test: /\.png$/,
type: 'asset/resource',
},
{
test: /\.svg$/,
type: 'asset/inline',
},
{
test: /\.txt$/,
type: 'asset/source',
},
{
test: /\.jpg$/,
type: 'asset',
parser: {
dataUrlCondition: {
maxSize: 8 * 1024,
},
},
},
],
},
};
上面的配置中，小于 8KB 的 jpg 图片会被转成 base64 data URI 内联，而大于阈值的 jpg 则作为单独文件输出。该行为与旧 url-loader 的 limit 参数类似，但配置路径从 loader options 移到了 parser.dataUrlCondition.maxSize。需要注意的是，如果仍然在同一个规则中混用 file-loader 和 type 字段，Webpack 会抛出错误，因为规则中的 type 和 loader 不能同时存在。迁移时通常只需要删除 use 数组里的文件类 loader，并把 type 设置为对应资源模块即可。
Asset Modules 的另一个好处是支持更精细的输出命名。可以通过 output.assetModuleFilename 全局设置，也可以在规则中使用 generator.filename。例如希望图片输出到 images 目录并保留扩展名，可以配置 generator: { filename: 'images/[name].[hash][ext]' }。这种能力让静态资源管理更集中，不再依赖 file-loader 的 name 选项。
二、Loader API 调整：getOptions 取代 this.query
在 Webpack 5 中，loader 函数内部获取配置项有了新方式。以前需要引入 loader-utils 调用 getOptions(this)，或者直接读取 this.query，现在可以直接使用 this.getOptions()。这个 API 内置于 loader 上下文，不需要额外依赖，并且支持传入 JSON Schema 进行参数校验。旧有的 this.query 属性虽然还能访问，但已被标记为废弃，继续使用会在控制台看到警告。
一个简单的自定义 loader 示例如下，它的作用是在每个源文件开头注入一段自定义注释：
// add-banner-loader.js
module.exports = function (source) {
const options = this.getOptions({
type: 'object',
properties: {
banner: { type: 'string' },
},
additionalProperties: false,
});
const banner = options.banner || '/* generated by webpack */';
return `${banner}\n${source}`;
};
使用这个 loader 时，在 webpack 配置中通过 options 传入 banner 字符串。如果传入的配置不符合 schema，比如 banner 被写成数字，Webpack 会在构建阶段直接报出校验错误，而不是等到 loader 运行时才出现难以追踪的异常。这种内置校验能让自定义 loader 更健壮，也减少了手工写参数检查代码的工作量。
除了 getOptions，Webpack 5 的 loader 上下文还扩展了 this.getResolve、this.getCompilation 等方法，并统一了内部模块解析逻辑。对于需要解析依赖路径的 loader，推荐改用 this.getResolve() 而不是直接调用 resolver，因为后者能正确处理配置中的 resolve 规则和插件。迁移旧 loader 时，优先将 this.query 替换为 this.getOptions()，再检查是否有依赖 loader-utils 的其他方法，通常这些方法已不再需要。
三、异步 Loader 与缓存机制的变化
Webpack 5 对异步 loader 的支持更友好，允许直接返回 Promise。旧写法需要先调用 this.async() 拿到 callback，然后在异步操作完成后调用 callback 返回结果。新写法可以直接把 loader 函数声明为 async，内部使用 await，最后 return 处理后的源码。这种风格与普通 JavaScript 异步编程一致，可读性更好，也避免了忘记调用 callback 导致的挂起问题。
例如一个读取同目录下额外文件并追加到源码的异步 loader：
// append-extra-loader.js
const fs = require('fs').promises;
const path = require('path');
module.exports = async function (source) {
const extraPath = path.join(this.context, 'extra.txt');
this.addDependency(extraPath);
const extra = await fs.readFile(extraPath, 'utf8');
return source + '\n' + extra;
};
这里调用 this.addDependency 是为了告诉 Webpack，extra.txt 也属于本模块的依赖。Webpack 5 默认启用持久化缓存，构建结果会缓存到磁盘，如果 loader 读取了外部文件但没有声明依赖，后续修改外部文件时可能不会触发重新构建。这个细节在旧版本缓存体系下影响不大，但在 Webpack 5 的 filesystem cache 中非常重要。
对于仍然希望使用 callback 风格的场景，this.async() 依然可用。调用后返回一个回调函数，第一个参数传错误，第二个参数传源码，还可以传递第三、第四个参数作为额外的结果和 sourceMap。Webpack 5 保留了这一机制，因此旧 loader 无需全部重写。不过新项目建议优先使用 Promise 返回方式，因为代码更短，错误处理也更符合 async/await 习惯。
四、迁移与常见问题
从 Webpack 4 迁移到 5 时，首先要检查配置里是否还依赖 file-loader、url-loader、raw-loader。如果项目中有这些包，最好先删除 package.json 中的依赖，再把 module.rules 里对应的 use 字段改成 type。对于个别第三方 loader 内部仍然使用 this.query 的情况，可以先保持现状，但应当在控制台查看弃用警告，并关注该 loader 的版本更新。大部分主流 loader 已经适配 Webpack 5，如果遇到不兼容的 loader，可以尝试使用兼容模式或寻找替代方案。
另一个容易忽略的问题是 asset 类型的阈值。旧 url-loader 通过 limit 控制是否内联，而 Webpack 5 的默认阈值是 8KB。如果项目之前设置的 limit 是 10000，迁移后需要显式在 parser.dataUrlCondition.maxSize 中设置相同数值，否则小文件处理策略可能和预期不一致。此外，处理字体文件时也可以使用 asset/resource，通常不需要内联，直接输出为独立文件即可。
缓存方面，如果启用了 experiments.cache 或使用 cache: true，需要确保自定义 loader 正确声明文件依赖。除了 this.addDependency，还可以使用 this.addContextDependency 声明整个目录，不过这样会使缓存失效范围变大，建议只在确实需要读取目录下多个文件时使用。在生产环境还可以配合 cache.buildDependencies 把配置文件本身也纳入缓存依赖，避免修改 webpack 配置后使用旧缓存。
总体上，Webpack 5 的 loader 相关变化以简化配置、减少外部依赖和提升缓存效率为目标。Asset Modules 让资源处理变成内置能力，getOptions 让参数读取和校验更规范，Promise 异步和持久化缓存则帮助大型项目获得更快的增量构建。掌握这些新特性后，可以更自信地升级构建工具链，也能写出更简洁、可维护的 loader 配置。