开发时页面突然卡住加载，控制台里请求 .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 | 快速处理流程
优先用轻量方案，速度快：
- 停止前端 dev 服务
- 在项目根目录（即 frontend 的上一级目录）确认路径无误后，删除缓存目录：
rm -rf frontend/node_modules/.vite - 重启前端服务
- 浏览器强制刷新
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一起成长~