开源生态的繁荣让前端项目可以快速借助海量第三方依赖完成功能开发，但每一个依赖包背后都携带一份许可证协议。如果团队在没有理清授权条款的情况下将 GPL 类强传染性许可证的代码打包进商业产品，就可能面临源码被迫公开甚至法律诉讼的风险。Webpack 5 针对这一痛点提供了许可证合规检查相关的能力，让构建工具在编译阶段就承担起审计职责，本文将围绕其原理、配置与实践展开详细说明。
为什么需要在构建阶段做许可证合规检查
传统的许可证审计往往发生在项目上线前，由法务或安全团队手工梳理依赖清单，这种方式有两个明显缺陷。第一是滞后性，当问题在上线前才被发现，替换依赖的成本极高，可能涉及大量代码重构；第二是不完整，手工梳理很容易遗漏间接依赖，而 npm 的依赖树中传递依赖往往占了绝大多数。
以一个典型的 React 项目为例，直接依赖可能只有二三十个，但执行 npm ls --all 后完整依赖树可能膨胀到上千个包。这些传递依赖同样会被打进最终的 bundle 中，它们的许可证条款同样具有法律效力。将检查动作前置到构建阶段，意味着每次打包都能自动获得一份最新的依赖许可证清单，问题可以在开发早期被发现和修复。
Webpack 5 的设计思路是让构建产物与许可证信息保持同步。无论依赖如何升级或增删，只要执行一次构建，合规报告就会随之更新，这从根本上解决了审计结果与实际产物脱节的问题。
Webpack 5 许可证检查的工作原理
Webpack 5 的许可证检查能力建立在模块联邦与新资源模块体系之上。其核心逻辑是：Webpack 在解析模块时已经完整遍历了依赖图，而 npm 包的 package.json 中包含 license 字段，Webpack 可以在遍历过程中收集这些信息，再通过 stats 或输出插件将结果落地为报告文件。
具体来说，Webpack 5 对 stats 输出做了增强，新增了与许可证相关的数据暴露能力。配合 stats.modulesSpace 等配置项，可以在 stats 对象中拿到每个模块所属包的详细信息，包括包名、版本号以及许可证字段。这一数据结构为上层工具实现合规判断提供了基础。
// webpack.config.js 基础配置示例
const path = require('path');
module.exports = {
mode: 'production',
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: '[name].[contenthash].js'
},
stats: {
// 输出模块的详细信息，包含许可证字段
modules: true,
moduleAssets: true,
reasons: false,
errorDetails: true
},
optimization: {
// 开启模块 ID 稳定化，保证报告可对比
moduleIds: 'deterministic'
}
};上述配置让 Webpack 在每次构建时输出包含模块归属信息的 stats 数据。需要注意的是，optimization.moduleIds 设置为 deterministic 非常重要，它保证同一份代码在不同机器上构建时模块 ID 保持一致，使得许可证报告具备可对比性与可追溯性。
使用 license-webpack-plugin 生成许可证清单
Webpack 5 原生数据结构提供了信息来源，但要生成一份人类可读的许可证清单文件，通常还需要借助插件。社区中使用最广泛的是 license-webpack-plugin，它会扫描参与构建的所有模块，读取各自 package.json 中的许可证声明，并输出一个聚合的文本文件到产物目录。
const LicenseWebpackPlugin = require('license-webpack-plugin')
.LicenseWebpackPlugin;
module.exports = {
plugins: [
new LicenseWebpackPlugin({
// 输出文件名，会生成在 output.path 目录下
outputFilename: ' THIRD-PARTY-NOTICES.txt ',
// 构建时发现的许可证不在白名单中则直接报错，阻断构建
unacceptableLicenseTest: (licenseIdentifier) => {
return /^(GPL|AGPL|LGPL)/.test(licenseIdentifier);
},
// 补充许可证缺失的包的信息
licenseTemplateFiles: {
'my-internal-package': 'licenses/my-internal-package.txt'
},
// 抑制无法解析许可证的告警（谨慎使用）
suppressLicenseOutputWarnings: false
})
]
};这段配置实现了两个关键能力。其一是产出 THIRD-PARTY-NOTICES.txt 文件，里面按字母序列出所有依赖包的名称、版本、作者、主页以及许可证全文，这个文件可以直接随产品发布，满足大多数开源许可证中关于再分发的声明义务。其二通过 unacceptableLicenseTest 定义黑名单规则，一旦某个依赖的许可证命中 GPL 系列前缀，构建将直接失败，从流程上强制拦截高风险依赖。
与手工维护第三方声明文件相比，这种方式的优势是显而易见的：清单永远与实际产物一致，新增依赖的当天就会被纳入审计范围，删除的依赖也不会在清单中留下垃圾条目。
构建自动化审计流程与告警机制
单次构建的合规报告只是第一步，成熟的团队会把它接入 CI/CD 流水线，形成持续审计。常见做法是在流水线脚本中安装 Webpack 与许可证插件，执行构建后解析报告文件，与预先定义的许可证策略做比对。
// scripts/license-check.js CI 阶段执行的比对脚本
const fs = require('fs');
// 团队策略：允许的许可证类型
const allowedLicenses = new Set([
'MIT', 'ISC', 'Apache-2.0',
'BSD-2-Clause', 'BSD-3-Clause', '0BSD'
]);
const report = fs.readFileSync(
'dist/THIRD-PARTY-NOTICES.txt', 'utf8'
);
// 用正则粗略提取每个包的许可证标识
const pattern = /\((MIT|ISC|Apache-2\.0|GPL-[0-9.]+|AGPL-[0-9.]+|BSD-[23]-Clause|LGPL-[0-9.]+|MPL-2\.0|Unlicense|0BSD)\)/g;
const found = new Set();
let m;
while ((m = pattern.exec(report)) !== null) {
found.add(m[1]);
}
const violations = [...found].filter(l => !allowedLicenses.has(l));
if (violations.length > 0) {
console.error('发现不合规许可证：', violations.join(', '));
process.exit(1); // 非零退出码使流水线失败并发出告警
}
console.log('许可证合规检查通过');脚本的核心是解析报告并将实际许可证集合与白名单求差集。一旦出现差集，脚本以非零退出码结束，CI 系统会据此标记流水线失败，并触发邮件或即时通讯工具的告警。这种机制把合规从人工审查变成了工程化的门禁，任何引入高风险依赖的合并请求都无法通过。
对于需要更细粒度控制的团队，还可以引入 license-checker 或 oss-attribution-generator 等工具作为补充，它们能扫描整个 node_modules 目录而非仅限参与打包的模块，覆盖未被 Webpack 引入但存在于依赖树中的包，两者结合可以做到产物级与依赖树级的双重审计。
常见问题与最佳实践
实践中最常见的问题是依赖包缺少 license 字段。一些老旧或个人维护的包确实存在这种情况，此时插件会输出警告。建议不要简单粗暴地关闭警告，而是通过许可证模板文件手动补全信息，并在代码仓库中记录补全依据，例如从包的 README 或仓库地址确认的真实许可证。
另一个实践要点是区分许可证的传染性等级。MIT、ISC、Apache-2.0 属于宽松许可证，只需保留版权声明即可；LGPL、MPL-2.0 属于弱传染性，需要注意模块边界；GPL、AGPL 则是强传染性，商用产品应默认拒绝。策略文件建议以白名单形式维护，只允许明确审核过的类型，这比黑名单更安全，因为黑名单无法覆盖未来出现的新许可证类型。
最后，许可证清单文件应纳入版本管理或作为构建产物归档。当项目需要应对客户审计或开源合规调查时，每一版产品的依赖构成与授权情况都有据可查，这正是 License Compliance Checking 特性为工程化交付带来的核心价值。
Webpack 5License Compliance许可证合规检查修改时间：2026-09-01 10:33:00