先确认现象：缓存为什么失效？

排查长期缓存问题时，我会先看构建产物文件名是否每次都有变化。如果是 Webpack 4 默认配置，每次新增或删除模块后，所有 chunk 的哈希都会变——因为模块 ID 是自增整数，增删模块导致后面模块的 ID 全部往后推。这时浏览器缓存几乎全量失效。Webpack 5 在长期缓存上的核心改进是引入了稳定的模块 ID 和 chunk ID，默认使用确定性算法生成。在 Webpack 4 中，默认 ID 是自增整数，一旦添加或删除模块，后续模块的 ID 会全部改变，导致缓存失效。Webpack 5 的 optimization.moduleIds: 'deterministic' 和 optimization.chunkIds: 'deterministic' 使 ID 基于模块路径和内容哈希生成，新增模块不会影响现有模块 ID，从而保持缓存有效性。

Webpack 5 在长期缓存上的核心改进是引入了稳定的模块 ID 和 chunk ID，默认使用确定性算法生成。在 Webpack 4 中，默认 ID 是自增整数，一旦添加或删除模块，后续模块的 ID 会全部改变，导致缓存失效。Webpack 5 的 `optimization.moduleIds: 'deterministic'` 和 `optimization.chunkIds: 'deterministic'` 使 ID 基于模块路径和内容哈希生成，新增模块不会影响现有模块 ID，从而保持缓存有效性。

升级到 Webpack 5 后，需要在配置中显式启用 `optimization.moduleIds: 'deterministic'` 和 `optimization.chunkIds: 'deterministic'`（Webpack 5 生产模式默认已启用）。如果使用 `splitChunks`，建议同时设置 `optimization.usedExports: true` 和 `optimization.innerGraph: true`，进一步减少未使用代码对 chunk 内容的影响。验证缓存效果时，可对比前后两次构建的输出文件，观察无改动的模块文件哈希是否保持不变。

容易误判的地方：版本升级后配置不生效

很多人升级到 Webpack 5 后仍发现缓存失效，是因为生产模式虽然默认启用了确定性 ID，但如果配置中手动覆盖了 moduleIds 或 chunkIds 为 false 或其他旧值，就会退化为自增逻辑。还有一种情况是开发环境未启用，导致本地调试时哈希总变，误以为生产环境也会出问题。升级到 Webpack 5 后，需要在配置中显式启用 optimization.moduleIds: 'deterministic' 和 optimization.chunkIds: 'deterministic'（Webpack 5 生产模式默认已启用）。如果使用 splitChunks，建议同时设置 optimization.usedExports: true 和 optimization.innerGraph: true，进一步减少未使用代码对 chunk 内容的影响。验证缓存效果时，可对比前后两次构建的输出文件，观察无改动的模块文件哈希是否保持不变。

建议的处理顺序

第一步：升级 Webpack 到 5.x 后，先确保 configuration 中没有手动设置过时的选项（比如 HashedModuleIdsPlugin 或 NamedModulesPlugin），它们会被 Webpack 5 自动忽略但可能引起混淆。第二步：在 webpack.config.js 中添加或确认 optimization.moduleIds: 'deterministic' 和 optimization.chunkIds: 'deterministic'，生产模式下可以不写（默认启用），但显式写出更明确。第三步：打开 runtimeChunk: 'single' 把运行时代码统一到一个文件中，避免多入口时 runtime 散落在各 chunk 里影响缓存。第四步：设置 output.pathinfo: false 和 optimization.realContentHash: true，前者去掉构建路径信息，后者确保哈希计算只依赖内容。第五步：重新构建一次，对比两次输出，观察未改动模块的哈希是否相同。

常见坑：动态 import 路径变量

即使启用了确定性 ID，如果代码中使用动态 import() 且路径包含变量或表达式，Webpack 5 仍可能生成不一致的 chunk ID。解决方案是保持动态导入路径为静态字符串，或使用 magic comments 显式指定 webpackChunkName。另外，Webpack 5 将 runtime chunk 抽取到独立文件后，若未正确配置 runtimeChunk: 'single'，会导致不同入口的 runtime 代码散落在各 chunk 中，影响长期缓存。建议在配置中强制设置 runtimeChunk: 'single'，同时检查动态导入的路径是否全部为字面量。

验证方法

构建完成后，打开 dist 目录，观察文件名哈希。也可以使用 webpack --profile --json > stats.json 生成统计文件，然后通过 webpack-bundle-analyzer 插件可视化查看模块 ID 分布，确认是否出现非预期的 ID 变化。另一种快速检查方法是手动修改一个模块内容（比如改一行注释），然后重新构建，看只有该模块所在的 chunk 哈希变了，其他 chunk 的哈希不变——这是长期缓存生效的标志。若发现所有文件哈希都变了，说明配置未生效。浏览器端可以配合 Cache-Control: max-age=31536000 等缓存策略，观察首次加载后资源是否从缓存加载（200 from disk cache 或 304）。

回滚和风险

如果升级后缓存效果不理想，可以暂时回退到 Webpack 4 的 NamedModulesPlugin 或 HashedModuleIdsPlugin，但这样做会失去 Webpack 5 的确定性优势。更稳妥的做法是先在非生产环境验证，确认哈希稳定性后再上线。注意，如果项目中使用了 DllPlugin 或 Externals，外部模块的版本变化仍然会导致 hash 改变，这是正常现象——长期缓存只能保证模块 ID 稳定，不能保证外部依赖版本不变。此外，不同操作系统（如 Windows 和 Linux）的路径分隔符差异可能导致构建结果不一致，建议统一环境或设置 output.pathinfo: false 来规避。

后续维护

长期缓存生效后，还需要关注几个点：一是定期检查 Webpack 版本更新，因为新版本可能调整默认行为；二是每次添加新模块时观察构建日志，确认没有异常 ID 变化；三是结合 CI/CD 流程，在每次构建后对比前后的 stats.json，自动化检测哈希变化是否合理。如果团队有多个项目依赖同一套组件库，推荐使用 ModuleFederationPlugin 共享模块，减少重复打包，进一步提升缓存命中率——但这需要额外配置，不在本文讨论范围。