Webpack 5 在模块构建体系里增加了一类被称为 linting rules 的能力，它让开发者可以在依赖解析和模块编译之前，对即将进入打包流程的模块内容或导入关系做校验。传统做法往往依赖 ESLint 等独立工具在编辑或提交阶段拦截问题，但这类工具无法直接感知 Webpack 的依赖图谱与解析器行为。Linting rules 则补齐了构建器自身的约束环节，使不符合团队规范的代码在打包时直接报错或警告。
linting rules 的设计原理与触发时机
在 Webpack 5 的内部流程中，当 resolver 完成模块路径解析、loader 即将对资源进行转换前，compiler 会派发一系列钩子。linting rules 本质上是基于 NormalModule 的钩子扩展，它允许在配置对象里声明一组匹配条件和校验函数。与普通 module rules 不同，linting rules 不会修改模块源码，也不会参与产物输出，仅仅返回一个诊断信息集合。
这种机制的核心价值在于“上下文感知”。例如 ESLint 无法判断某个文件是否因为动态导入而被重复打包，但 Webpack 在构建依赖树时已经掌握了完整的引用链路。通过在 linting rules 中读取 module.dependencies，我们可以写出检查循环依赖的逻辑。下面的代码展示了如何注册一个最基础的 linting 规则：
module.exports = {
module: {
rules: [
{
test: /.js$/,
enforce: 'pre',
use: {
loader: 'built-in-lint-loader'
}
}
],
lintingRules: [
{
test: /.js$/,
check: function(module, diagnostics) {
if (module.rawRequest && module.rawRequest.indexOf('legacy') >= 0) {
diagnostics.addWarning('禁止使用 legacy 目录下的模块');
}
}
}
]
}
};
上面的配置中，lintingRules 是 Webpack 5 暴露的新字段，其每一项都包含 test 正则与 check 回调。回调接收当前模块对象和诊断收集器，开发者可自由推送错误或警告。由于它运行在构建主线程且早于 loader 执行，因此不会显著增加打包耗时。
与 ESLint 及自定义 loader 的对比方案
很多团队习惯用 ESLint 配合 pre-commit 钩子来保证代码质量，但这种方式存在两个盲区。第一，ESLint 规则与 Webpack 解析配置（如 alias、extensions）脱节，容易出现本地校验通过但构建失败的情况。第二，ESLint 难以基于打包后的依赖结构做判断。Linting rules 因为内嵌在 Webpack 内部，可以直接复用 resolver 的结果，避免重复配置。
另一种常见做法是写自定义 loader 做校验，但 loader 本质是用来转换代码的，强行在里面抛错会打断正常的 module 替换逻辑，且无法聚合多个文件的联合诊断。Linting rules 则专门分离了“校验”与“转换”职责。从下表可以看出三者在关键维度上的差异：
| 方案 | 感知依赖图 | 是否改源码 | 配置复杂度 |
|---|---|---|---|
| ESLint | 否 | 否 | 低 |
| 自定义 loader | 部分 | 可能 | 中 |
| Webpack linting rules | 是 | 否 | 低 |
实践中，推荐将硬性架构约束（如禁止跨层引用）放在 linting rules，将代码风格类检查留给 ESLint。这样既能利用构建器的全局视野，又不会让单一工具负担过重。下面示例演示了如何禁止从视图层直接导入数据层模块：
module.exports = {
module: {
lintingRules: [
{
test: /src/views/.*.js$/,
check: function(module, diagnostics) {
const deps = module.dependencies || [];
deps.forEach(function(dep) {
if (dep.request && dep.request.indexOf('src/models') >= 0) {
diagnostics.addError('视图层禁止直接依赖 models 层: ' + dep.request);
}
});
}
}
]
}
};
该规则在每次构建时扫描视图模块的所有依赖，一旦发现指向 models 的引用便记录错误，从而把分层架构违规拦截在集成之前。相比在代码评审中靠人工发现，这种自动化手段更加稳定。
在持续集成中落地 linting rules 的最佳实践
将 linting rules 接入 CI 流程时，需要注意诊断信息的输出格式。Webpack 5 默认会把 linting 警告和错误合并到统计信息里，我们可以通过 stats 配置将其单独提取。建议在 CI 脚本中设置 failOnWarning: false 但 failOnError: true，避免风格类提示阻断流水线，而结构性错误必须修复。
另外一个容易被忽略的点是缓存。Webpack 5 的持久化缓存会记录模块指纹，如果仅修改了 linting 规则的逻辑，可能不会触发重新校验。此时应在规则文件变更时清理 node_modules/.cache 或配置 cache.version 字段。下面的配置片段说明了如何为 linting 逻辑设定缓存版本：
module.exports = {
cache: {
type: 'filesystem',
version: 'lint-rules-v1'
},
module: {
lintingRules: require('./lint-rules.config')
}
};
当团队扩充了校验维度，只需把 version 改为 lint-rules-v2，即可强制所有模块重新经过新规则检查。结合 monorepo 场景，还可以针对不同子包传入差异化的 lintingRules 数组，实现局部治理。通过把质量关口前移到构建器内部，前端工程化体系能够获得更低的维护成本与更高的约束执行力。
Webpack_5linting_rulesmodule_build修改时间：2026-08-16 16:32:29