Vite 依赖预构建缓存失效怎样定位

Vite 依赖预构建缓存“失效”时，通常不是一个缓存，而是两个层次叠在一起：Vite 在项目目录中的 node_modules/.vite 文件系统缓存，以及浏览器对解析后依赖请求的 HTTP 缓存。定位时先看开发服务器是否重新执行依赖扫描，再看浏览器 Network 是否仍命中旧的依赖响应，最后才决定是否使用 --force。

官方地址：https://vite.dev/

本文不把“页面还是旧的”直接等同于 Vite 没有重建，而是用三项可观察基线来拆开问题：冷启动耗时、终端里的依赖重新优化提示、Network 面板中依赖请求的缓存状态。

先用三项基线判断是哪一层在变化

先不要删除 node_modules。重新启动开发服务器，记录冷启动到页面可访问的大致耗时，并观察终端是否出现依赖重新扫描、重新生成优化结果或页面需要重新加载的提示。这个记录是后面判断的基线。

这三行不是性能承诺，而是排障记录模板。重点是把“启动发生了什么”和“浏览器最后拿到了什么”分开记，避免在两个缓存层之间来回猜。

文件系统缓存的失效输入要逐项对照

Vite 官方文档说明，依赖预构建只用于开发模式，缓存目录默认是 node_modules/.vite。Vite 会根据包管理器 lockfile、patches 目录修改时间、相关 vite.config 字段以及 NODE_ENV 判断是否需要再次预构建。因此，刚切换分支、改了 optimizeDeps，或只改变了运行环境变量，都可能让原来的优化结果不再适用。

可以先检查这些输入，而不是把“缓存目录存在”当成“缓存一定有效”：

# 只查看决定依赖预构建的常见输入，不修改项目文件
printf 'NODE_ENV=%s\n' "${NODE_ENV:-未设置}"
ls -ld node_modules/.vite 2>/dev/null || echo 'node_modules/.vite 尚不存在'
find . -maxdepth 1 -type f \( -name '*lock*' -o -name 'package.json' \) -print
test -d patches && find patches -maxdepth 1 -type f -print

# 用于排查配置变化；不要把整个 node_modules 当作第一步清理目标
rg -n "optimizeDeps|NODE_ENV|defineConfig" vite.config.* package.json 2>/dev/null

如果 lockfile 或配置确实刚发生变化，正常的重新扫描并不代表故障。相反，如果明明改了依赖入口但启动日志完全没有变化，才需要继续检查当前启动命令是否指向了预期项目目录，以及配置文件是否被实际加载。

浏览器强缓存会把正确的重建结果遮住

即使 Vite 已经生成了新的预构建结果，浏览器也可能继续使用之前解析后的依赖请求。Vite 文档说明，这类请求带有很长的 max-age 和 immutable 缓存策略；当 lockfile 反映出不同版本时，Vite 会通过追加版本查询参数让浏览器重新获取。

排查时打开浏览器开发者工具的 Network 面板，临时勾选禁用缓存，再刷新页面。这个动作只用于隔离浏览器层，不等于永久关闭缓存。随后用 --force 重启 Vite，让两层状态重新对齐：

# 强制忽略已有优化结果，重新生成开发依赖预构建
npm run dev -- --force

# 如果项目脚本不是 npm，保留同一个 --force 语义
pnpm dev --force
# yarn dev --force
# bun run dev --force

如果禁用浏览器缓存后页面立刻正常，而普通刷新仍旧异常，问题重点在浏览器缓存；如果只有 --force 后才正常，重点在 node_modules/.vite 或依赖扫描输入。两者都有效，说明此前同时存在旧的文件系统结果和旧的浏览器响应。

按症状选择最小恢复动作

定位完成后，恢复动作可以按影响范围从小到大排列：

1. 只怀疑浏览器响应：先临时禁用 Network 缓存并刷新，确认是否只是旧响应。
2. 依赖入口、lockfile 或 Vite 相关配置刚变更：重启开发服务器；需要明确忽略旧优化结果时再加 --force。
3. 链接包或依赖内容在本地变化：检查它是否被正确识别为源码，必要时在 optimizeDeps.include 中明确纳入，再用 --force 重启。
4. 只有在上述动作仍无法消除确定的本地缓存残留时，才单独删除 node_modules/.vite 并重新启动；不要把删除整个依赖目录作为默认排查动作。

最终判断可以压缩成一句话：日志告诉你 Vite 有没有重新计算，Network 告诉你浏览器有没有重新取数；两个证据都拿到后，缓存失效问题就不再是模糊的“Vite 不生效”。

常见追问

为什么只改了 vite.config.js 就需要重新预构建？

因为相关配置字段会参与依赖优化结果的判断。配置是否相关取决于它影响的插件和依赖解析，不是所有任意字段都会改变预构建结果，所以应先看启动日志而不是每次都手动清缓存。

依赖预构建缓存会影响生产构建吗？

本文讨论的是开发模式的 dependency pre-bundling。生产构建有自己的构建流程和缓存，不应把 node_modules/.vite 的现象直接当成生产产物问题。

为什么删除缓存后浏览器仍显示旧代码？

删除的是 Vite 文件系统缓存，不会自动清除浏览器已经保存的依赖响应。请用 Network 面板临时禁用缓存并刷新，确认浏览器层之后再判断是否需要继续调整 Vite 配置。