Webpack 从 5.0 版本开始引入了基于文件系统的持久化缓存（Persistent Caching），配置方式非常简单，只需要在 webpack.config.js 中写上 cache: { type: 'filesystem' }，第二次构建就能跳过大量重复的模块编译工作，构建速度往往能提升数倍。但实际使用中，很多人发现日志中频繁出现类似 "unable to determine dependency snapshot information, cache busting" 的提示，缓存几乎每次都在重建，提速效果大打折扣。要理解这个问题，就必须搞清楚 Webpack 内部是如何判断一个模块"变没变"的——这正是 hash 与 timestamp 两种失效判定策略发挥作用的地方。
一、Webpack 是如何判断缓存是否失效的
Webpack 的文件系统缓存并不是把整个项目打包结果原样存下来，而是以模块为单位，把每个模块的编译产物连同它的"快照信息"（snapshot）一起序列化到磁盘缓存目录中。下次构建时，Webpack 会为当前模块重新生成一份快照，与缓存中的快照进行比对，如果两者一致，就直接复用缓存的编译产物，跳过整个编译流程。
快照信息里包含两类关键内容：一类是时间戳和文件大小等元数据，另一类是文件内容的哈希值。判断文件是否变化时，Webpack 有一套优先级逻辑：默认情况下，如果文件的时间戳和大小都没变，就认为文件没有变化，直接复用缓存；只有当时间戳发生变化时，才会进一步计算文件内容的哈希值来确认内容是否真的改变了。
这套设计是很聪明的。计算哈希需要读取整个文件内容并执行摘要运算，对于大型项目来说，几万个文件全部算一遍哈希的开销并不小。而时间戳比对只需要一次 stat 调用，成本几乎可以忽略。所以默认策略是"时间戳优先、哈希兜底"，兼顾了速度和准确性。但这也埋下了几个隐患：如果某个工具只改了文件内容却没更新 mtime，时间戳比对就会误判文件没变，导致缓存污染；反过来，如果某个流程频繁 touch 文件（比如 git checkout 切换分支），时间戳变了但内容没变，就会触发大量不必要的哈希计算。
二、snapshot 配置：精细化控制失效判定的颗粒度
Webpack 在 cache.snapshot 配置项中暴露了几个参数，允许开发者调整判定策略。常用的配置如下：
module.exports = {
cache: {
type: 'filesystem',
snapshot: {
// 对依赖包是否使用时间戳判断
managedPaths: ['/my_modules'],
// 对不可变路径（内容永不变化的文件）只比对时间戳
immutablePaths: [],
// 构建依赖的时间戳与哈希配置
buildDependencies: {
hash: true, // 使用内容哈希判断
timestamp: true // 使用时间戳判断
},
// 模块的时间戳与哈希配置
module: {
hash: true,
timestamp: true
}
}
}
};timestamp 和 hash 这两个开关可以同时开启，也可以只开一个。如果关掉 hash 只留 timestamp，速度最快但存在误判风险；如果关掉 timestamp 只留 hash，判断最精确但每次都要读文件算哈希，在大仓库里会比较慢。实践中比较稳妥的组合是：对项目源码（src 目录）两者都开，对 node_modules 这种内容基本不可变的目录，用 immutablePaths 标记后只做时间戳比对即可。
还有一个容易踩的坑是 buildDependencies。这个配置告诉 Webpack 哪些文件是"构建依赖"——一旦这些文件变化，整个缓存就应该作废重来。典型用法是把 webpack 配置文件本身和 babel 配置放进去：
module.exports = {
cache: {
type: 'filesystem',
buildDependencies: {
// 建议使用绝对路径，指向配置文件目录
config: [__filename]
}
}
};注意 buildDependencies 的失效判定同样受 timestamp 和 hash 配置影响。如果配置文件被格式化工具重写过，比如加了几个空格，时间戳变了但内容语义没变，开启 hash 判定后 Webpack 会发现哈希实际没变化语义层面……实际上哈希会因为空格而改变，所以缓存仍然会失效。这也是为什么有些团队在接入 Prettier 之后，第一次格式化全量代码会导致持久化缓存整体重建。理解了这一点，就应该把格式化操作安排在缓存稳定之后，或者接受一次重建的代价。
三、排查缓存失效的常见原因与排查手段
配置看起来没问题但缓存仍然频繁失效，这时候需要借助日志定位。给构建命令加上 --cache-logging 或在配置中开启相关输出后，Webpack 会打印缓存失效的具体原因。除此之外，最常见的几个"隐形杀手"值得逐一排查。
第一个是 version 字段。Webpack 默认会把自身的版本号、loader 版本等写入缓存标识，任何一项变化都会导致缓存作废。比如 CI 环境中每次安装依赖，如果 lock 文件不严格，某个 loader 小版本升级了，缓存就全废了。解决办法是固定依赖版本，或者在 cache 配置中显式声明 version，让自己掌控失效时机。
第二个是绝对路径问题。持久化缓存默认与机器绑定的路径有关，如果项目目录发生变化（比如 CI 上每次检出路径带随机后缀），缓存命中率会大幅下降。这种情况需要在 cache 配置中设置 name，把路径相关的因素隔离掉。第三个是 resolve 配置。Webpack 会把 resolve 选项（alias、extensions、modules 等）作为缓存依赖，任何动态生成这些配置的写法——例如每次构建时生成一个新的随机目录名并塞进 alias——都会让缓存形同虚设。看一个反面案例：
module.exports = {
resolve: {
alias: {
// 每次构建生成不同目录，缓存直接报废
'@tmp': `/tmp/build-${Date.now()}`
}
}
};这种写法下，每次构建的 resolve 配置都不一样，Webpack 判定所有模块的解析结果不可信，只能全部重新编译。正确的做法是固定临时目录名，或者通过内容哈希来命名而不是时间戳。
最后总结一下实践建议：对源码目录保持默认的时间戳加哈希双重判定；用 immutablePaths 标记 node_modules 中的不可变部分以提升比对速度；把配置文件纳入 buildDependencies；固定所有依赖版本避免 CI 环境下的版本漂移；排查时优先看日志中的失效原因提示，再顺着 snapshot 判定链路逐层定位。只要把这些细节处理好，filesystem 缓存的二次构建基本能稳定在首建的十分之一左右耗时，提速效果非常可观。
Webpack文件系统缓存hashtimestamp修改时间：2026-09-04 03:02:44