Vite 开发调试与故障排查：devtools、调试工具链与常见问题定位

① 配置层：vite.config.js 的解析与生效
② CLI 层：dev/build 的启动参数与日志
③ 运行时层：浏览器里的模块加载、HMR、产物

npx vite --debug           # 打印详细请求日志（dev）
npx vite build --debug     # 构建详细日志
npx vite --host            # 监听所有地址（局域网调试）
npx vite build --sourcemap # 产物带 sourcemap

npx vite --debug                    # 每个模块请求打印（找加载路径）
npx vite --host 0.0.0.0             # 局域网访问（手机调试）
npx vite --port 5173 --strictPort   # 端口固定，端口被占就报错而非换
npx vite --force                    # 强制重新预构建

vite:resolve 为 '/@fs/Users/.../src/App.tsx' 解析依赖
vite:transform 转换 /src/main.tsx
→ 能看到每个模块的解析、转换过程 → 定位"哪个模块慢/挂"

- 端口被占 → 默认自动 +1，想要固定用 --strictPort
- 后端代理：vite.config 里 server.proxy 配错 → 前端 404
- host 限制：只 localhost 时手机/局域网打不开 → --host

node --inspect-brk node_modules/vite/bin/vite.js
# 再在浏览器 DevTools 里 attach 调试 Vite 自身逻辑

npx vite build --debug          # 详细打包日志
npx vite build --sourcemap      # 生成 sourcemap（生产排错用）
npx vite build --mode staging   # 指定模式（环境变量）

# 常见三种
npx vite build --report                      # 依赖体积报告（需插件）
npx vite-plugin-bundle-visualizer            # 可视化依赖图
ls -S dist/assets/ | head                    # 看最大 chunk

- build --sourcemap → dist/assets/*.js.map
- 线上报错堆栈 → 用 sourcemap 还原到源码
- 注意：sourcemap 会泄露源码，公网要谨慎（可仅内网/上传到错误追踪平台）

// vite.config.js
export default {
  build: { sourcemap: true },   // 开发友好 / 生产按需
};

- --debug 看哪一步耗时（转换/打包）
- 大依赖（某 chunk 巨大）→ 拆包或动态 import
- 没开缓存 → 见 /vite-build-cache/

① Network：看模块加载 → 找 404、大文件、重复请求
② Sources：配好 sourcemap → 断点打到源码
③ Performance：录制 → 找慢模块（加载/解析/执行）

- dev 模式：一堆 /src/xxx.tsx 请求 → 看哪个 404/失败
- 瀑布图：哪个模块加载最慢（网络或转换）
- 重复加载：同一模块出现两次 → 路径不统一（别名问题）

// 在浏览器 console 里
// Vite 5 起可在页面上看到模块依赖（vite:inspect 插件）
import { inspect } from "vite-plugin-inspect";   // 依赖图查看

- 打开 Performance → 录制 → 交互
- 看 Long Task、脚本执行时间
- 对比"加载哪个 chunk 花了最久"

① 依赖装了吗？（node_modules 存在？）
② Vite 能解析吗？（裸模块 → 查 node_modules）
③ 预构建正常吗？（.vite/deps 有没有该依赖）
④ 路径对了吗？（相对路径/别名/大小写）

npx vite --debug 2>&1 | grep resolve
# 能看到 vite:resolve 对每个 import 的解析过程与最终路径

- 依赖在 .vite/deps 里找不到 → 可能没被 optimizeDeps 收录
- 强制重建：--force 或删 node_modules/.vite
- 声明 include：vite.config 里 optimizeDeps.include

export default {
  optimizeDeps: {
    include: ["my-unoptimized-lib"],    // 主动声明预构建
  },
};

- 多版本依赖（react 18 vs 19）→ package.json 去重或 npm dedupe
- exports 字段缺失的包 → 用 main 兜底（resolve.mainFields）
- 大小写不一致（Import vs import）→ 严格路径

// vite.config.js
import path from "node:path";
export default {
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
      "@components": path.resolve(__dirname, "src/components"),
    },
  },
};

□ 别名用绝对路径（path.resolve）——相对路径在嵌套时会错
□ tsconfig 也要配 paths 与 alias 一致（不然类型报错）
□ 别名为空字符串会匹配一切 → 别用 '' 做前缀
□ 优先用别名替换绝对前缀，别混用 /@/ 等
□ 修改别名后要重启 dev server（配置变化才生效）

- 报错"cannot resolve '@/xxx'" → 别名没生效/路径写错
- 开发正常构建挂 → 检查构建环境（base、alias 是否被 tree-shake）
- 用 --debug 看解析到的实际路径

// tsconfig.json 要与 vite 别名一致
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] },
    "baseUrl": "."
  }
}

① 改了文件 → 终端有没有 HMR 日志？（"hmr update /src/xxx"）
② 浏览器 Network 有没有更新推送？
③ 边界（import.meta.hot.accept）有没有正确接住？
④ 组件被 HMR 边界隔离了？（动态 import/工厂函数会断链）

- 只有"接受更新的模块"会热更，否则整页 reload
- React Fast Refresh：组件文件自动接受；非组件要自己 accept
- 动态 import 的模块、工厂返回的组件 → 可能不触发 HMR

// 需要手动接受的场景
import.meta.hot?.accept();

npx vite --debug 2>&1 | grep -i hmr   # 看 HMR 推送
# 浏览器 console 也会有 hot update 日志

npx vite --debug 2>&1 | grep -E "耗时|optimize|transform"

① 依赖预构建慢：依赖多/版本乱 → optimizeDeps.include 收敛、去重依赖
② 冷启动扫描慢：大项目 → 用 workspace/缓存、减少首启扫描
③ 首屏模块多：→ 按需/懒加载、减少同步 import

- 单个文件更新要重转换 → 大依赖链拖慢
- 样式/CSS 全量 → 独立 chunk 减少波及面
- 模块图太大 → 拆包、子树边界

- optimizeDeps.include：预声明关键依赖（跳过首次请求触发）
- 减少无意义的 import（副作用树摇）
- 升级 Vite（构建优化持续改进）
- 使用 Vite 5+ 的持久化缓存改进（见 /vite-build-cache/）

npx vite --debug | grep -i "module" | sort | tail   # 最慢模块
# 或用 vite-plugin-inspect 看依赖图里的大节点

1. 复现最小：删掉无关代码，最小可复现
2. 看日志：--debug / 终端输出 / 浏览器 console
3. 二分：禁用部分插件/配置，找出元凶
4. 求文档：--version 报版本、查 changelog