Vite默认将预构建产物存于node_modules/.vite/deps目录并生成_metadata.json记录哈希与映射，以实现ESM转换、消除请求瀑布流及通过?v=xxx控制浏览器缓存；强制刷新需用--force、删.vite或触发哈希变更。

Vite 默认把预构建产物存在 node_modules/.vite/deps 目录里，这是它为了提升开发启动和热更新速度做的本地缓存机制。这个目录不是你手动创建的，而是 Vite 启动时自动检测依赖、用 esbuild 打包后写入的。同时还会生成一个 _metadata.json 文件，记录每个依赖的哈希值、版本标识和文件映射关系，用来判断是否需要重新构建。

预构建产物为什么默认放在这里

Vite 的设计原则是“零配置开箱即用”，所以它会自动扫描源码里的裸导入（比如 import { debounce } from 'lodash-es'），识别出哪些第三方包需要预构建，然后统一放进 node_modules/.vite/deps。这样做的好处是：

• 浏览器请求 /node_modules/.vite/deps/lodash-es?v=abc123 时能直接命中本地文件，避免反复解析 CommonJS 或处理深层嵌套模块
• 每个依赖被打包成单个 ESM 文件，解决请求瀑布流问题
• 通过查询参数 ?v=xxx 控制浏览器缓存，确保版本变更时强制刷新

如何强制刷新预构建缓存

当遇到以下情况时，旧缓存可能失效或不一致，需要强制刷新：

• 更新了 package.json 中的依赖版本
• 修改了 vite.config.ts 里的 optimizeDeps 配置（如 include/exclude）
• 引入了新依赖但页面报错或跳转刷新异常
• 使用了 monorepo 中的 linked package，且源码有改动

可用的方法有三种，按推荐顺序排列：

• 启动时加 --force 参数

  

  用于自动切换项目中适合的node 版本

  根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。

  下载

  npm run dev -- --force
  # 或
  vite --force

  这是最干净的方式，Vite 会跳过所有缓存判断，直接清空 .vite/deps 并重新扫描、预构建全部依赖。

• 手动删除 .vite 目录

  rm -rf node_modules/.vite
  # Windows 用户可用：
  rmdir /s /q node_modules\.vite

  删除后下次启动自动重建，适合脚本化清理或 CI 环境。

• 修改依赖的哈希触发重构建
  Vite 会比对 _metadata.json 中的 browserHash 和当前 package-lock.json、node_modules 实际内容。你只需做任意一项就能让哈希不匹配：

  • 安装一个新包（npm install xxx）
  • 升级已有包（npm update vue）
  • 修改 vite.config.ts 中影响预构建的字段（如 optimizeDeps.include）

注意：仅清除浏览器缓存（Ctrl+F5 或禁用缓存调试）不够，因为 Vite 的 HTTP 强缓存头 Cache-Control: max-age=31536000,immutable 会让浏览器一年内都不发请求——必须同步清理服务端缓存（即 .vite/deps）才能生效。

不复杂但容易忽略