Webpack 的 module.rules 配置决定了每种文件由哪些 loader 来处理。很多人写了十几条 rule 之后发现构建速度越来越慢，却不知道问题可能出在规则匹配的方式上。默认情况下，Webpack 处理每个模块时，会把 rules 数组中的所有规则依次测试一遍，即使某个文件已经命中了 test 条件，后面的规则依然会被检查。这在规则条数较多的项目里会产生不小的开销。oneOf 属性正是针对这个问题的优化手段，它能让匹配过程在命中第一条规则后立即终止。
一、默认匹配行为与 oneOf 的区别
要理解 oneOf 的价值，先要看清楚默认的匹配机制。假设你的 rules 里配置了 babel-loader 处理 js 文件、css-loader 处理 css 文件、file-loader 处理图片，那么当一个 .js 文件进入编译流程时，Webpack 会把这个文件依次与每条规则的 test 条件做比对。js 文件只会命中 babel-loader 那一条，但 css 和图片的规则照样会被测试一次。单个文件的开销微不足道，可一个中大型项目动辄几千个模块，每个模块都要遍历全部规则，累积起来的耗时就很可观了。
oneOf 改变了这个行为。把若干条规则放进一个 oneOf 数组后，Webpack 会按顺序逐条检查，只要某一条规则的 test 命中了当前文件，就直接采用这条规则并停止检查后面的规则。用一句话概括：默认模式是「全部过一遍，命中的都生效」，oneOf 模式是「命中即停，只取第一条」。这也解释了为什么大多数项目的实际需求恰好适合 oneOf——一个文件通常只需要一组 loader 来处理。
二、oneOf 的具体配置写法
下面是一个典型的开发环境配置示例，把处理不同类型文件的规则统一放进 oneOf 数组。注意 oneOf 本身是一个数组，每個元素都是一条完整的规则对象，写法和普通 rule 完全一致：
module.exports = {
module: {
rules: [
{
// oneOf 数组内的规则，命中一条后立即停止匹配
oneOf: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader']
},
{
test: /\.less$/,
use: ['style-loader', 'css-loader', 'less-loader']
},
{
test: /\.(jpg|png|gif)$/,
type: 'asset/resource',
generator: {
filename: 'images/[hash:8][ext][query]'
}
},
{
test: /\.js$/,
exclude: /node_modules/,
loader: 'babel-loader',
options: {
presets: ['@babel/preset-env']
}
},
{
// 兜底规则：不写 test，任何文件都能命中
exclude: /\.(js|css|less|jpg|png|gif|html)$/,
type: 'asset/resource'
}
]
}
]
}
};这里有一个非常实用的技巧值得注意。oneOf 内部是按声明顺序匹配的，如果把 test 条件宽松的规则放在前面，会「抢走」本应由后面的规则处理的文件。比如把 /\.js$/ 的规则放在 /\.m?js$/ 之前，某些文件的加载结果就会和你预期的不同。另外，数组末尾那条不写 test 的规则充当了兜底角色，任何没有被前面规则命中的文件都会落到它身上，通常用来把剩余的静态资源当作资源文件直接输出。
还有一点容易被忽略：如果文件在 oneOf 数组里没有任何一条规则命中，Webpack 会直接抛出错误，提示你可能需要一个合适的 loader 来处理该文件。而默认的 rules 数组遇到这种情况时，如果外面还有普通规则，依然可以兜住。因此在迁移配置时要确保覆盖了项目中所有出现的文件类型，或者保留那条兜底规则。
三、oneOf 与 enforce、eslint-loader 的配合使用
有些规则并不是用来转换文件的，而是做代码检查，比如以前的 eslint-loader（现在推荐用 eslint-webpack-plugin）。这类规则的特点是：检查完之后文件本身还要继续交给 babel-loader 处理。这类需要「叠加生效」的规则就不能放进 oneOf，因为 oneOf 里命中一条后就不再执行其他规则了。
正确的做法是把需要叠加的规则放在 oneOf 外面，作为普通规则声明。利用 enforce: 'pre' 属性可以让它优先执行，这样 eslint 检查总是发生在 babel 转换之前，一旦发现语法错误能第一时间报出来：
module.exports = {
module: {
rules: [
{
// 普通规则：对所有 js 文件先做语法检查
test: /\.js$/,
enforce: 'pre',
exclude: /node_modules/,
loader: 'eslint-loader',
options: {
fix: true
}
},
{
oneOf: [
{
test: /\.js$/,
exclude: /node_modules/,
loader: 'babel-loader'
},
{
exclude: /\.(js|html|css)$/,
type: 'asset/resource'
}
]
}
]
}
};这种「外层普通规则加内层 oneOf 数组」的组合是社区公认的最佳实践。外层放需要同时生效的规则，例如代码检查、缓存相关的处理；内层 oneOf 放互斥的转换规则，例如各类文件格式对应的 loader。两者搭配既保证了功能完整性，又获得了匹配效率上的提升。
四、使用 oneOf 的注意事项与性能收益
oneOf 虽然好用，但有几个坑需要留意。第一，oneOf 数组内不能出现 test 条件重叠且顺序颠倒的规则，否则后面的规则永远不会被执行，等于白写。第二，oneOf 只能包含没有 resolve.only 等特殊约束的常规规则，每条规则内部仍然可以使用 exclude、include、issuer 等条件属性，灵活度不受影响。第三，如果你的项目中确实存在一个文件需要经过多组不同 loader 处理的场景（比如 vue 单文件组件中 template、script、style 各自分流），那这些规则就应该依靠 loader 内部的机制去分流，而不是全部堆在 module.rules 里互相竞争。
关于性能收益，oneOf 带来的提升主要体现在规则数量多、模块数量大的项目中。假设你有 20 条规则和 3000 个模块，默认模式下匹配次数是 6 万次，而使用 oneOf 后，平均每个模块只需测试到命中为止，匹配次数大幅下降。虽然单次匹配只是正则或字符串比对，速度很快，但在开启增量编译、频繁触发热更新的开发场景下，这个差异会被放大，表现为文件修改后重新构建的响应更及时。对于追求极致构建速度的团队，oneOf 通常会与 cache、thread-loader、缩小 include 范围等手段一起使用，共同构成完整的构建优化方案。
总结一下，oneOf 的核心价值在于把「遍历全部规则」变成「命中即停」，配置成本低，收益稳定，几乎没有副作用。如果你的项目 rules 数组已经超过五条，不妨现在就检查一下配置，把互斥的转换规则收进 oneOf，把需要叠加的规则留在外层，构建速度的提升往往立竿见影。