vite-deploy-doctor

一个专门检查前端项目上线部署风险的命令行工具，支持 Vite 和 Vue CLI / webpack 项目。

它的目标不是替代 ESLint、TypeScript 或单元测试，而是帮你在上线前发现这些常见问题：

• 本地正常，线上资源 404
• 生产包里仍然请求 localhost、内网 IP、旧接口地址
• Vite base 配置错误
• Vue CLI publicPath / outputDir 配置不合理
• .env.production 缺失或包含本地地址
• Nginx history 路由刷新 404
• WebSocket / Socket.IO 代理配置缺失
• 构建阶段因为缺失图片、缺失模块、错误 import 导致失败

效果预览

运行浏览器报告模式后，可以在本地页面中查看按错误、警告、提示、通过分组后的检查结果。

支持的项目

Vite 项目

支持 Vue + Vite、React + Vite、Svelte + Vite、Vanilla + Vite 等项目。

会重点检查：

• vite.config.*
• Vite base
• .env.production
• VITE_* 环境变量
• dist/index.html
• dist 构建产物

Vue CLI / webpack 项目

支持使用 vue-cli-service 的 Vue CLI 项目。

会重点检查：

• vue.config.js
• publicPath
• outputDir
• .env.production
• VUE_APP_* 环境变量
• webpack 构建产物

安装

推荐在项目中安装为开发依赖：

npm install -D vite-deploy-doctor

也可以直接使用：

npx vite-deploy-doctor --help

快速使用

在你的前端项目根目录执行：

npx vite-deploy-doctor

中文输出：

npx vite-deploy-doctor --lang zh-CN

打开浏览器报告页面：

npx vite-deploy-doctor --ui --lang zh-CN

执行生产构建后再分析：

npx vite-deploy-doctor --build --ui --lang zh-CN

指定项目目录：

npx vite-deploy-doctor --root ./web --ui --lang zh-CN

指定构建产物目录：

npx vite-deploy-doctor --dist dist
npx vite-deploy-doctor --dist xh-system

输出 JSON：

npx vite-deploy-doctor --json

推荐 npm scripts

Vite 项目

{
  "scripts": {
    "build": "vite build",
    "doctor": "vite-deploy-doctor --ui --lang zh-CN",
    "doctor:build": "vite-deploy-doctor --build --ui --lang zh-CN",
    "doctor:ci": "vite-deploy-doctor --json"
  }
}

Vue CLI 项目

如果原来的生产构建命令是：

{
  "scripts": {
    "build:prod": "vue-cli-service build"
  }
}

推荐添加：

{
  "scripts": {
    "build:prod": "vue-cli-service build",
    "doctor": "vite-deploy-doctor --build --build-command \"npm run build:prod\" --ui --lang zh-CN"
  }
}

之后只需要执行：

npm run doctor

如果你希望直接用 npm run build 打开体检报告，可以这样配置，避免递归调用：

{
  "scripts": {
    "build": "vite-deploy-doctor --build --build-command \"npm run build:prod\" --ui --lang zh-CN",
    "build:prod": "vue-cli-service build"
  }
}

浏览器报告模式

使用：

vite-deploy-doctor --ui --lang zh-CN

工具会启动一个本地页面：

http://127.0.0.1:随机端口/?lang=zh-CN

页面能力：

• 按 错误 / 警告 / 提示 / 通过 分组
• 点击顶部概览卡片筛选对应问题
• 展示具体文件路径
• 展示中文修复建议
• 构建失败时展示中文诊断和原始日志
• 支持复制 JSON 报告

指定端口：

vite-deploy-doctor --ui --port 4188

不自动打开浏览器：

vite-deploy-doctor --ui --no-open

构建检查

默认情况下，工具只扫描当前已有的配置和构建产物。

如果你想发现这些问题：

• 删除了图片导致打包失败
• import 了不存在的模块
• 构建时路径大小写错误
• webpack / Vite 编译失败

请使用：

vite-deploy-doctor --build --ui --lang zh-CN

如果工具没有自动识别正确的构建命令，可以手动指定：

vite-deploy-doctor --build --build-command "npm run build:prod" --ui --lang zh-CN

构建失败时，报告会尽量给出中文诊断，例如：

构建失败原因：源码中引用了一个不存在的文件或模块。
缺失资源：../../../assets/img/actaver.png
引用位置：src/views/layout/components/Header.vue
处理建议：恢复这个文件，或修改引用路径，或删除相关引用后重新构建。

当前检查项

项目识别

• 识别 Vite 项目
• 识别 Vue CLI / webpack 项目
• Vue CLI 项目会跳过 Vite 专属检查，减少误报

生产环境变量

• 检查 .env.production 是否存在
• Vite 项目检查 VITE_*
• Vue CLI 项目检查 VUE_APP_*
• 检查环境变量中是否包含本地地址或内网 IP

构建产物扫描

扫描 html、js、css、json、svg 等文件，检查：

• 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://

Vite 配置

• 检查 vite.config.*
• 检查 base
• 子路径部署时检查 base 是否建议以 / 结尾

Vue CLI 配置

• 检查 vue.config.js
• 检查 publicPath
• 检查 outputDir
• 子路径部署时检查 publicPath 是否建议以 / 结尾

index.html 资源引用

• 检查构建后的 index.html
• 检查 JS / CSS / 图片 / favicon 是否缺失
• 结合 Vite base 或 Vue CLI publicPath 映射资源路径

Nginx history 路由

如果检测到 history 路由，但没有发现 Nginx 配置，会提示你检查：

location / {
  try_files $uri $uri/ /index.html;
}

子路径部署时，例如 /xh-system/：

location /xh-system/ {
  try_files $uri $uri/ /xh-system/index.html;
}

WebSocket / Socket.IO 代理

检测源码中是否使用：

• new WebSocket(...)
• socket.io-client
• io(...)
• ws://
• wss://

如果使用了 WebSocket，但没有发现 Nginx upgrade 配置，会提示检查：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

命令参数

--root <path>              指定项目根目录
--dist <path>              指定构建产物目录
--lang <locale>            输出语言：zh-CN 或 en-US
--json                     输出 JSON 报告
--ui                       启动浏览器报告页面
--port <port>              指定 UI 端口
--no-open                  不自动打开浏览器
--build                    执行生产构建后再扫描
--build-command <command>  指定生产构建命令

退出码

0  没有错误
1  存在错误

警告和提示不会让命令失败，只有 error 会导致退出码为 1。

适合什么时候使用

推荐在这些场景使用：

• 前端项目准备上线前
• 修改部署路径后
• 修改 .env.production 后
• 切换服务器、域名、接口地址后
• 打包后发现线上资源 404
• history 路由刷新 404
• WebSocket 线上连接失败
• 想在 CI/CD 中提前发现部署风险

暂不支持

当前不会检查：

• 页面样式错位
• 真实线上接口是否可用
• 线上 Nginx 是否已经部署正确
• 后端跨域配置是否正确
• 运行时权限问题
• 浏览器兼容性问题
• 首屏性能和包体积分析

这些能力可以在后续版本继续扩展。

License

MIT