Vite 报 504 Outdated Optimize Dep？先删 .vite 缓存

开发时页面突然卡住加载，控制台里请求 .vite/deps/chunk-xxx.js 返回 504 Outdated Optimize Dep，这种情况笔者遇到过几次。它通常不是代码写错了，而是 Vite 的预构建依赖缓存出了问题。

01 | 问题现象与根因

现象很直接：页面加载卡住，浏览器请求 .vite/deps/chunk-xxx.js 时返回 504 Outdated Optimize Dep。

常见原因是 Vite 预构建依赖的缓存损坏或过期，导致缓存里的 chunk 和当前依赖版本对不上；具体触发条件以所用 Vite 版本的官方文档和实际日志为准。常见触发场景有三个：切换 git 分支、增删 package 依赖、服务非正常退出。

flowchart TD A[页面卡住加载] --> B[请求 .vite/deps/chunk-xxx.js] B --> C{返回 504<br/>Outdated Optimize Dep} C -->|是| D[预构建依赖缓存损坏或过期] D --> E[缓存 chunk 与当前依赖版本不匹配] E --> F1[切换 git 分支] E --> F2[增删 package 依赖] E --> F3[服务非正常退出]

02 | 快速处理流程

优先用轻量方案，速度快：

1. 停止前端 dev 服务
2. 在项目根目录（即 frontend 的上一级目录）确认路径无误后，删除缓存目录：rm -rf frontend/node_modules/.vite
3. 重启前端服务
4. 浏览器强制刷新 Ctrl+Shift+R

这里要特别注意：只删 .vite 目录，不要删整个 node_modules，这样能节省大量时间。

flowchart TD S[出现 504 Outdated Optimize Dep] --> A[停止前端 dev 服务] A --> B[删除 frontend/node_modules/.vite] B --> C[重启前端服务] C --> D[浏览器强制刷新 Ctrl+Shift+R] D --> E{问题是否解决} E -->|是| F[完成] E -->|否| G[进入兜底方案]

03 | 兜底方案

如果上面的步骤无效，再进入 frontend 目录执行 npm install（该命令会按 package.json 与 lockfile 重建依赖，可能更新 node_modules，请确认 lockfile 变更符合预期），然后重复一遍：停服务 → 删 .vite 缓存 → 重启，并观察控制台是否仍返回 504。

flowchart TD A[快速处理流程无效] --> B[进入 frontend 目录] B --> C[执行 npm install] C --> D[停止前端 dev 服务] D --> E[删除 .vite 缓存] E --> F[重启前端服务] F --> G{控制台是否仍返回 504} G -->|否| H[完成] G -->|是| I[结合官方文档与实际日志进一步排查]

需要说明的是，这一整套操作只清理前端编译缓存，不影响后端代码，也不影响业务数据库数据。

04 | 预防提示

切换分支、修改 package.json 之后，如果遇到资源加载异常，可优先清理 Vite 预构建缓存，这通常比全量重装 node_modules 更快；但若依赖本身未正确安装或 lockfile 不一致，仍需先执行依赖安装。

一句话精简版：Vite 报 504 Outdated Optimize Dep，优先删 node_modules 下的 .vite 缓存，重启前端，强制刷新浏览器；无效再重新 npm install，不碰业务数据。

---

关注我，和AI一起成长~