Webpack 的持久化缓存将模块编译结果和依赖图序列化到磁盘，二次构建时通过对比文件系统快照来决定哪些缓存条目仍然有效。snapshot 配置正是控制这种对比粒度的核心开关，其中 resolveBuildDependencies 负责决定是否把解析模块时用到的构建依赖文件纳入快照监测。这个选项看似不起眼，却直接影响修改 package.json 之后能否让缓存自动失效。下面结合配置结构来梳理它的作用。

snapshot 在持久化缓存中的位置

持久化缓存并不是简单地把所有文件哈希一次然后对比，它需要区分不同类型的文件依赖。Webpack 在编译阶段会记录模块路径、文件依赖、上下文依赖和缺失依赖等信息，这些信息最终会汇总到快照中。快照的生成方式由 snapshot 字段统一控制，包含 managedPaths、immutablePaths、resolveBuildDependencies 等子项。

其中 managedPaths 和 immutablePaths 主要用于减少 node_modules 等目录的监听开销，而 resolveBuildDependencies 则影响解析阶段产生的构建依赖是否被记录。如果没有把这类依赖放进快照，构建系统就无法感知 package.json 或 lock 文件的变化，容易出现旧缓存被继续使用的问题。

从配置角度看，snapshot 通常和 cache.type: 'filesystem' 搭配使用。只有启用了文件系统缓存，快照对比才有持久化的意义。如果使用内存缓存，快照只存在于单次进程内，resolveBuildDependencies 的默认行为仍然生效，但不会产生跨进程的缓存复用问题。

resolveBuildDependencies 的默认行为与内部逻辑

resolveBuildDependencies 的默认值为 true。在模块解析阶段，resolver 会读取模块所在目录的 package.json、node_modules 中的依赖描述文件、lock 文件以及部分工具配置，例如 TypeScript 的 tsconfig.json。这些文件统称为构建依赖。当该选项开启时，Webpack 会为这些文件创建快照条目，并在后续构建时比较它们的时间戳、文件大小或内容哈希，具体比较方式由 snapshot.module 和 snapshot.resolve 的哈希策略决定。

可以把构建依赖理解为解析结果的一部分：如果一个模块的解析结果依赖于某个 package.json 中声明的依赖版本，那么该 package.json 就应该参与缓存失效判断。如果不这样做，即使 package.json 中新增了一个依赖，resolver 的解析路径可能已经改变，但旧缓存仍然指向旧的解析结果，从而产生错误构建。默认开启这个选项能够弥补这种隐式依赖的追踪缺口。

需要注意的是，resolveBuildDependencies 与 cache.buildDependencies 不是同一个概念。后者要求显式列出哪些文件变化时需要废弃整个缓存，例如 webpack.config.js 自身、环境变量文件等。前者则是自动收集解析过程中实际读取过的文件。两者可以同时使用，一个负责用户态配置，一个负责解析态依赖，共同组成完整的缓存失效依据。

配置与调优实践

在大多数项目中，保持 resolveBuildDependencies 为默认值即可，不需要额外设置。但在某些特殊场景下，比如构建依赖非常多、文件系统监听压力较大，或者明确知道某些解析依赖不会影响产物时，可以考虑关闭该选项以降低快照生成和对比的成本。配置方式如下：

module.exports = {
  cache: {
    type: 'filesystem',
  },
  snapshot: {
    resolveBuildDependencies: false,
    managedPaths: [/[\\/]node_modules[\\/]/],
  },
};

关闭之后，修改 package.json 可能不会让缓存自动失效，因此必须通过其他手段弥补，例如将 package.json 添加到 cache.buildDependencies.config 中。不过这种做法只适合依赖结构非常稳定的项目，否则很容易引入难以排查的缓存污染问题。

更常见的调优是保留默认开启，同时通过 managedPaths 和 immutablePaths 减少不必要的监听。例如把 node_modules 标记为托管路径，Webpack 会使用包版本和元数据来生成快照，而不是逐文件记录，从而降低开销。这种情况下，resolveBuildDependencies 依然会记录解析过程中读取的依赖文件，只是这些依赖文件的快照生成方式也会受到托管路径策略的影响。

另一个值得关注的场景是 monorepo。当多个 package 相互依赖且解析时会跨包读取 package.json 时，resolveBuildDependencies 的作用范围会扩大。此时如果发现修改子包依赖描述后构建没有触发相应的缓存失效，可以先检查该选项是否被无意关闭，再检查快照的 resolve 部分是否启用了足够强的哈希策略。

验证缓存失效与排查思路

要验证 resolveBuildDependencies 是否按预期工作，可以通过修改一个被依赖模块的 package.json，然后观察二次构建是否重新编译了相关模块。更精确的做法是开启 Webpack 的缓存调试日志。示例如下：

module.exports = {
  cache: {
    type: 'filesystem',
    name: 'my-cache',
  },
  infrastructureLogging: {
    debug: /webpack\.cache/,
  },
};

运行构建后，日志中会输出缓存条目被标记为失效的原因，例如某个文件的时间戳发生变化。如果 package.json 被修改后日志中没有出现对应的失效记录，而构建结果又没有更新，说明 resolveBuildDependencies 可能未生效，或者该 package.json 不在解析依赖的收集范围内。

排查这类问题时，可以先确认 snapshot.resolveBuildDependencies 的布尔值，然后检查 Webpack 版本对应的默认值是否发生变化。还可以临时将 cache.type 改回 memory，观察问题是否消失，以判断是否与持久化缓存的快照对比有关。如果是因为配置文件自身变化未被检测，则需要把配置文件路径加入 cache.buildDependencies.config，而不是依赖 resolveBuildDependencies 来处理。

最终，这个选项的核心价值在于补全解析阶段隐式依赖的追踪。正确理解并配置它，可以让构建缓存在性能与准确性之间得到更可靠的平衡。