大家好最近我做了一个前端部署检查工具名字叫vite-deploy-doctor它是一个专门检查前端项目上线部署风险的命令行工具主要面向Vite / Vue / 前端静态项目部署场景。项目地址https://www.npmjs.com/package/vite-deploy-doctorGitHub 地址https://github.com/BlueStarBigBoy/vite-deploy-doctor如果你也遇到过下面这些问题这个工具可能会对你有帮助本地运行正常部署到线上后资源 404线上环境还在请求localhost打包后接口地址还是旧 IPVitebase配置错误.env.production没生效Vue Router history 模式刷新页面 404Nginx 配置不完整WebSocket / Socket.IO 线上连接异常这些问题很多时候不是代码逻辑错了而是构建配置、环境变量、静态资源路径、Nginx 配置出了问题。所以我做了这个小工具希望在上线前提前发现这些风险。一、为什么要做这个工具做前端项目时大家应该都遇到过这种情况本地pnpm dev一切正常。接口能请求页面能打开路由能跳转图片也能显示。结果一上线页面空白 资源 404 接口请求 localhost 刷新详情页 404 WebSocket 连接失败这类问题最烦的地方是本地看不出来只有上线后才暴露。而且很多时候排查过程非常痛苦。比如线上接口还在请求本地地址http://localhost:3000/api/xxx或者http://192.168.1.100:8080/api/xxx这通常说明生产环境变量没有正确生效或者代码里写死了接口地址。再比如 Vite 项目部署到子路径https://example.com/timeroom/如果vite.config.ts里的base没配对打包后的资源路径就可能变成/assets/index-xxx.js最终线上直接 404。所以我想做一个工具在项目上线前执行一次检查提前告诉你这里可能有问题 这里可能导致线上 404 这里可能还残留 localhost 这里 Nginx 配置可能不完整这就是vite-deploy-doctor的初衷。二、vite-deploy-doctor 是什么vite-deploy-doctor是一个命令行工具。它不会替代 ESLint、TypeScript 或单元测试。它关注的不是代码风格而是前端项目部署上线相关的风险检查。比如Vite base 配置 生产环境变量 dist 打包产物 Nginx history 路由 WebSocket 代理配置 静态资源路径 localhost / 内网 IP 残留简单来说它是一个前端项目上线前体检工具。三、安装和使用可以直接通过 npx 使用npx vite-deploy-doctor也可以安装到项目中npm i vite-deploy-doctor -D然后执行npx vite-deploy-doctor如果你想指定项目目录npx vite-deploy-doctor --root ./your-project如果你的打包目录不是dist也可以指定npx vite-deploy-doctor --dist build如果想输出 JSON 格式npx vite-deploy-doctor --json四、它能检查哪些问题目前主要检查以下几类问题。1. 检查项目是否是 Vite 项目工具会检查项目根目录下的package.json判断是否存在 Vite 相关依赖。如果没有找到package.json会提示你可能没有在项目根目录执行。如果没有找到 Vite 依赖也会给出提示。2. 检查.env.production很多前端项目都会使用环境变量区分本地和线上。比如VITE_API_BASE_URLhttps://api.example.com但是实际开发中经常出现这些问题.env.production 忘记创建 变量名写错 生产环境变量没有生效 把敏感信息写进 VITE_ 变量需要注意的是Vite 中以VITE_开头的变量会暴露到客户端代码中。所以类似下面这种配置就很危险VITE_SECRET_KEYxxxx VITE_TOKENxxxx VITE_PASSWORDxxxxvite-deploy-doctor会检查这些可疑变量并给出风险提示。3. 检查 dist 中是否残留 localhost / 内网 IP这是我个人觉得最实用的功能之一。工具会扫描打包产物中的js css html检查是否包含localhost 127.0.0.1 0.0.0.0 192.168.x.x 10.x.x.x 172.16.x.x - 172.31.x.x http://数字 IP如果发现会提示类似Found suspicious address localhost in dist/assets/index-xxx.js这类问题非常常见。比如你本来以为线上接口已经改成了https://api.example.com但打包产物里实际还残留http://localhost:3000上线后自然就请求失败了。4. 检查 Vite base 配置如果你的项目部署在根路径https://example.com/问题一般不大。但如果你的项目部署在子路径https://example.com/timeroom/就需要特别注意 Vite 的base配置。例如export default defineConfig({ base: /timeroom/ })如果这里配置错误常见结果就是首页能打开但是 JS / CSS / 图片 404vite-deploy-doctor会检查vite.config.ts/vite.config.js中的base配置并提示可能的问题。比如base 没有配置 base 不是以 / 开头 base 不是以 / 结尾 base 可能和部署路径不匹配5. 检查 dist/index.html 资源路径打包后的index.html中如果出现类似script typemodule src/assets/index-xxx.js/script在根路径部署时没问题。但如果项目部署在/timeroom/这种子路径下就可能导致资源路径错误。工具会检查dist/index.html中是否存在/assets/这种绝对资源路径并提醒你确认base是否正确。6. 检查 Nginx history 路由配置如果你使用的是 Vue Router history 模式线上刷新详情页时可能会出现 404。比如https://example.com/timeroom/rooms/1本地能打开线上刷新 404。通常需要在 Nginx 中配置try_files $uri $uri/ /index.html;如果你的项目部署在子路径还需要结合实际路径调整。vite-deploy-doctor会扫描项目中的.conf文件检查是否存在类似的 history fallback 配置。7. 检查 WebSocket / Socket.IO 代理配置如果项目中使用了 WebSocket 或 Socket.IONginx 代理一般需要配置proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;否则线上可能出现WebSocket 连接失败 Socket.IO 一直轮询 实时通信不生效工具会尝试检测项目中是否存在 WebSocket / Socket.IO 相关关键词。如果发现项目中有相关使用但 Nginx 配置中缺少 upgrade header就会给出提示。