常见陷阱与最佳实践

本章汇总 Vite 开发中最常见的陷阱和推荐的最佳实践，并附带上线前检查清单。

常见陷阱汇总

开发环境

构建产物的坑

框架特有的坑

最佳实践清单

项目配置

• 使用 defineConfig 包裹配置获取 TS 类型提示
• 根据 command / mode 条件加载插件
• 设置 resolve.alias 路径别名并在 tsconfig.json 中同步
• .env 文件分层：.env（默认）、.env.development、.env.production
• .env.local 加入 .gitignore
• 敏感信息绝不用 VITE_ 前缀（或配置严格的 envPrefix）

开发阶段

• 启动时用 --open 自动打开浏览器
• 代理 API 请求到后端 server.proxy
• 动态 import 的包加入 optimizeDeps.include
• 大型项目配置 server.warmup 预热关键文件
• WSL2/Docker 用户配置 server.watch.usePolling

构建阶段

• 选择合适的 build.target（现代项目用 modules 或 es2020）
• 配置合理的代码分割策略 manualChunks
• 外部化库模式的依赖
• 生产构建关闭 sourcemap（或 'hidden'）
• 使用 rollup-plugin-visualizer 分析构建产物
• index.html 内 script / link 使用相对路径或正确的 base

部署阶段

• 部署前运行 vite preview 本地验证构建产物
• 非根路径部署设置 base
• 配置 Nginx/CDN 强缓存静态资源（带 hash 的文件）
• index.html 设为 no-cache
• 启用 gzip / brotli 压缩

生产检查清单

上线前逐项确认：

□ 构建成功：npm run build 无报错
□ 本地预览：npm run preview 功能正常
□ 路由模式：SPA fallback 已配置（Nginx try_files / 服务器重定向）
□ API 代理：生产环境 API 地址正确（环境变量或 base URL）
□ 子路径：若部署在子路径，base 已设置且末尾含 /
□ 静态资源：所有资源正确加载（路径、CDN）
□ sourcemap：已关闭或设为 hidden（不暴露源码）
□ 环境变量：生产变量以 VITE_ 前缀正确配置
□ 缓存策略：HTML 不缓存，assets/ 强缓存
□ CSP（内容安全策略）：若启用，Vite 开发时的 ESM 和 eval 不受影响
□ HTTPS：生产环境强制启用
□ 压缩：CDN / Nginx 中 gzip/brotli 已开启
□ 体积告警：chunk 体积在合理范围（单文件 < 500KB gzip）
□ 浏览器兼容：build.target 匹配目标用户群
□ 错误监控：Sentry 等工具已接入并配置 sourcemap 上传

Vite 专属调试技巧

查看预构建结果

# 检查预构建缓存
ls node_modules/.vite/

# 手动清除并重新预构建
rm -rf node_modules/.vite
vite --force

开发阶段查看模块图

// 安装 vite-plugin-inspect
npm i -D vite-plugin-inspect

import inspect from 'vite-plugin-inspect'

export default defineConfig({
  plugins: [inspect()],
})

访问 http://localhost:5173/__inspect/ 查看模块转换的中间状态。

HMR 调试

// 在浏览器控制台中查看 HMR 日志
if (import.meta.hot) {
  import.meta.hot.on('vite:beforeUpdate', (payload) => {
    console.log('HMR 即将更新:', payload)
  })
  import.meta.hot.on('vite:afterUpdate', (payload) => {
    console.log('HMR 已完成更新:', payload)
  })
  import.meta.hot.on('vite:error', (payload) => {
    console.error('HMR 错误:', payload)
  })
}

常见启动错误速查

升级 Vite 版本

npm i -D vite@latest

重大版本变化

💡 最佳实践：升级前先阅读 Vite 发布说明 的 Breaking Changes 部分。

环境变量安全

🚨 安全警告：任何以 VITE_ 开头的环境变量都将打包进客户端 JS 文件，用户可以直接查看。永远不要在其中存放密钥、令牌、密码等敏感信息。