Webpack 5 带来了一项对前端工程化影响深远的改进，那就是基于文件系统的持久化缓存。在此之前，Webpack 4 及更早版本虽然也有缓存机制，但默认只存在于内存之中，每一次命令行启动新的构建进程，之前花费大量时间完成的模块解析、编译和优化结果都会灰飞烟灭。Webpack 5 的持久化缓存将编译过程中的中间产物写入磁盘，使得二次构建甚至跨天构建都能复用已有结果，从根本上改变了大型项目构建缓慢的困境。
持久化缓存的工作原理与核心配置
Webpack 5 的缓存系统分为内存缓存和文件系统缓存两层。当配置中指定 cache.type 为 filesystem 时，构建过程中生成的模块代码、AST、依赖关系以及编译后的资源都会被序列化后保存到磁盘目录中，默认路径是 node_modules/.cache/webpack。在后续构建启动时，Webpack 会先读取这些缓存文件，通过比对每个模块的哈希值、loader 配置和整体构建参数的哈希，判断缓存是否仍然有效。
如果某个源文件内容没有变化，并且相关的 loader 与插件配置也未改动，那么对应模块的编译产物就直接反序列化到内存，跳过耗时的语法解析与转换步骤。这种机制依赖于精确的哈希追踪，Webpack 内部会为每一个参与构建的要素计算出一个指纹，只要指纹一致就认为可复用。因此，持久化缓存并不是简单地把上次的输出存起来，而是一套细粒度的依赖快照系统。
开启该功能的基础配置非常直观，在 webpack.config.js 中加入如下代码即可启用文件系统缓存：
const path = require('path');
module.exports = {
// 其他配置省略
cache: {
type: 'filesystem',
cacheDirectory: path.resolve(__dirname, '.temp_cache'),
buildDependencies: {
config: [__filename]
}
}
};
上面的 cacheDirectory 指定了缓存存放位置，而 buildDependencies 告诉 Webpack 当配置文件本身变化时应当让缓存整体失效。如果不设置这一项，修改了 webpack 配置但缓存未刷新，就可能出现难以排查的构建异常。此外，还可以通过 cache.name 为不同构建环境设置隔离的缓存空间，避免开发和生产构建互相污染。
性能收益对比与实测数据分析
为了理解持久化缓存到底带来了多少提升，我们可以观察一个中型单页应用项目的构建耗时。该项目包含约八百个模块，使用了 babel、ts-loader 以及多种样式处理 loader。在 Webpack 4 环境下，冷构建平均需要二十六秒，而没有任何缓存帮助的二次构建也要接近二十三秒，因为每次进程重启内存缓存都清零了。
迁移到 Webpack 5 并开启 filesystem 缓存后，首次构建仍然需要约二十五秒去生成并写入缓存，但紧接着的二次构建骤降到七秒左右，提速接近七成。如果连续多次修改不同业务模块，由于只失效了少数文件对应的缓存条目，大多数模块依旧命中磁盘缓存，构建时间稳定在八到九秒。在 CI 环境中若能够保留缓存目录，流水线耗时也从原本的四分钟缩减到一分半以内。
下面这张简表展示了不同场景下的耗时差异：
| 构建工具版本 | 缓存状态 | 平均耗时（秒） |
|---|---|---|
| Webpack 4 | 内存缓存（进程重启失效） | 23 |
| Webpack 5 | 文件系统缓存未命中 | 25 |
| Webpack 5 | 文件系统缓存命中 | 7 |
从表中能看出，持久化缓存的代价仅仅是首次写入的一点开销，而后续每一次构建都在享受复用红利。不过也要注意，如果项目极度依赖动态生成的临时文件，或者 loader 中频繁注入当前时间戳，会导致哈希不断变化、缓存几乎无法命中，这种情况下需要先优化代码生成逻辑，再谈缓存收益。
生产环境避坑与缓存策略优化
不少团队在初次使用持久化缓存时，遇到过“改了代码但打包结果没变”的问题。这通常是因为 buildDependencies 没有涵盖所有影响编译的要素，比如某个环境变量文件或全局 polyfill 脚本未被纳入追踪。Webpack 只认配置里声明的依赖，因此建议把 package.json、.babelrc 以及所有自定义插件路径都加进 buildDependencies 列表中，确保相关变动能触发缓存失效。
另一个常见误区是盲目共享缓存目录。在 monorepo 或者多项目共用一台构建机时，若多个项目写入同一个 cacheDirectory 且未通过 cache.name 区分，就会出现模块错乱。正确做法是为每个子项目配置独立的缓存名，或者直接使用默认的项目级 node_modules/.cache 路径，不手动指定全局目录。对于 CI，可以利用对象存储定期上传下载缓存包，但要注意版本兼容性，Webpack 缓存格式在不同小版本间不一定完全兼容。
在极端追求速度的场景，还可以结合 snapshot 配置调整文件时间戳的检测精度。默认的 timestamp 模式在部分网络文件系统上会有性能损耗，可切换为 hash 模式让 Webpack 通过内容哈希判断变动，虽略微增加 CPU 负担，却能在慢速磁盘上获得更稳定的缓存表现。总之，持久化缓存是一把利器，但只有理清依赖边界与运行环境，才能让它真正服务于构建效率而非制造诡异 bug。
Webpack_5persistent_cache build_performance修改时间：2026-08-18 00:58:33