Webpack 5 正式发布后，官方 Documentation 文档进行了一次较大的结构调整和内容扩充。与 Webpack 4 时代偏向 API 查询的文档风格不同，Webpack 5 的文档更加强调迁移指引、场景化示例以及新特性的设计动机。很多开发者在升级后仍然沿用旧版配置，遇到问题才去翻文档，结果发现文档中已经明确标注了废弃项和推荐替代方案。因此，系统性地浏览一遍 Webpack 5 的 Documentation，对后续项目维护和性能优化会有直接帮助。
一、文档结构调整：从 API 参考转向迁移与场景指南
Webpack 5 官方文档最明显的变化是新增了独立的迁移指南章节，并且将资源模块、缓存策略、模块联邦等内容提升到了一级导航。旧版文档中分散在 configuration 和 plugins 下的零散说明，现在被整合成带有完整背景介绍和代码示例的专题页面。例如 Asset Modules 章节详细对比了 raw-loader、url-loader、file-loader 与内置 asset/resource、asset/inline 之间的差异，并且给出了迁移时的等价写法。
这种调整背后的逻辑是让开发者先理解某个新特性解决什么问题，再看具体配置。以缓存章节为例，文档不再只列出 cache 配置项的类型和默认值，而是先用一段文字说明 Webpack 5 的持久化缓存如何通过文件系统缓存模块和 chunk，再展示开启 cache.type: 'filesystem' 后二次构建速度的变化。这样的叙述方式降低了照搬配置却不知道为什么的风险。
如果你还没有完整看过 Webpack 5 的文档目录，建议优先浏览 Migration Guide、Asset Modules、Caching 和 Module Federation 这几个部分。它们不仅覆盖了最常用的升级场景，也给出了大量可复制的配置片段。接下来本文会围绕这几个文档重点展开，并补充 stats 配置生成构建文档的实践技巧。
二、利用 stats 配置输出结构化构建文档
Webpack 5 对 stats 选项进行了增强，允许开发者通过命令行或配置文件输出非常详细的构建信息。这些信息可以保存为 JSON 文件，作为项目构建文档的一部分。与 Webpack 4 相比，Webpack 5 的 stats 输出中增加了更多关于模块关系、导出信息以及优化过程的字段，方便进行依赖分析和体积排查。
要生成一份完整的 JSON 构建报告，可以在命令行中执行 webpack --json > stats.json。不过默认输出的 JSON 会包含大量冗余字段，直接阅读非常困难。更推荐的做法是在配置文件中精细控制 stats 的字段，例如只保留 modules、reasons、assets 和 errors，同时关闭颜色输出。下面是一个适合生成文档的配置示例：
module.exports = {
// 其他配置省略
stats: {
all: false,
assets: true,
modules: true,
maxModules: 0,
reasons: true,
errors: true,
errorDetails: true,
warnings: true,
colors: false
}
};
运行构建后，将终端输出重定向到文件，就可以得到一份纯文本的模块依赖关系文档。如果还需要机器可读的格式，可以使用 --json 参数。很多团队会把这份 JSON 报告接入 CI 流程，当构建体积或模块数量发生异常波动时自动告警。Webpack 5 文档中专门有一节讲解 stats 的字段含义，建议在配置前先查阅 options 部分，避免收集过多无用数据导致报告体积过大。
除了手动配置 stats，Webpack 5 还提供了 stats.preset 选项，可以快速切换为 verbose、normal、minimal 等预设。在排查构建性能问题时，使用 minimal 预设能够快速定位错误，而 verbose 预设则适合生成详细的模块依赖图。如果你需要长期维护一份构建文档，将 stats 输出与 git 仓库中的 markdown 文件结合会是一个不错的实践。
三、Module Federation 文档中的完整示例与常见误区
模块联邦是 Webpack 5 最受关注的新特性，官方文档为它单独开辟了篇幅不短的章节，并且提供了完整的 host 与 remote 示例。文档中的示例代码直接复制下来基本可以运行，但很多人在实际项目里还是踩了坑，主要原因是忽略了文档中关于共享依赖和版本控制的说明。
模块联邦的核心配置项包括 exposes、remotes 和 shared。文档中用一个简单的按钮组件演示了如何将 remote 应用中的模块暴露出去，并在 host 应用中动态加载。下面是一个精简后的 remote 配置示例：
// remote 应用 webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'app1',
filename: 'remoteEntry.js',
exposes: {
'./Button': './src/components/Button'
}
})
]
};
对应地，host 应用需要声明 remotes 来引用 remote 暴露的模块，并使用动态 import 加载。文档中特别提醒，remote 的地址在开发环境通常是本机端口，在生产环境则需要替换为 CDN 地址。很多人一开始把 remotes 写死为 localhost，上线后才发现问题。Webpack 5 文档为解决这一问题提供了外部变量占位符的示例，通过将地址写在 index.html 的全局变量中，再在配置里用 promise 方式返回，从而实现环境切换。
另一个容易混淆的点是 shared 依赖的版本控制。文档明确指出，如果 host 和 remote 共享同一个库，需要将该库配置到 shared 数组中，并且可以设置 singleton 和 requiredVersion。如果不配置 shared，两个应用会各自打包一份相同的依赖，导致运行时出现多个实例，进而引发状态不一致的问题。官方文档用一个完整的 React 微前端示例演示了 singleton: true 的配置效果，建议在真正拆分微前端之前先跑通这个示例。
四、配置校验与类型提示：让文档活起来
Webpack 5 的一个重要改进是内置了配置对象的 schema 校验。当你传入一个错误的配置项或类型不匹配的值时，构建过程会立即报错并给出清晰的提示。官方文档中列出了所有配置项的 schema 定义，同时提供了 TypeScript 类型声明文件，这让编辑器的智能提示成为可能。
如果你使用 VS Code 并开启了 TypeScript 支持，可以在项目根目录添加一个 jsconfig.json 或 tsconfig.json，把 webpack 的配置文件纳入类型检查范围。配置完成后，输入 module.exports = { 再输入一个字母，编辑器会根据 webpack 的类型定义自动补全配置项，并在你输入错误值时显示警告。这种方式把文档从静态页面变成了实时提示，极大降低了配置出错率。
下面是一个 jsconfig.json 的示例，用于让 VS Code 识别 webpack.config.js 中的类型：
{
"compilerOptions": {
"checkJs": true,
"allowJs": true,
"types": ["node"]
},
"include": ["webpack.config.js"]
}
需要注意的是，类型提示只对使用 CommonJS 风格的配置文件生效，ES Module 写法需要额外的转换配置。Webpack 5 文档中对此也有说明，并且提供了在 package.json 中设置 type: 'module' 后如何使用 import 语法的示例。无论选择哪种模块规范，类型提示都能帮助你快速回忆配置项名称和可选值，减少反复查阅文档的次数。
总的来说，Webpack 5 的 Documentation 文档不再是简单的配置字典，而是围绕新特性、迁移路径和最佳实践组织起来的学习资料。把文档与 stats 报告、类型提示结合起来，既可以快速解决升级问题，也能建立起可持续维护的构建知识库。
Webpack5Documentation文档模块联邦修改时间：2026-09-28 11:19:20