Vite 模式

环境变量

• 仅以 VITE_ 为前缀的变量会暴露给客户端代码 —— DB_PASSWORD 保留在服务端，VITE_API_URL 会被打包进前端产物
• 通过 import.meta.env.VITE_* 访问，而非 process.env —— process.env 仅在 Node.js 环境中有效，在浏览器中为 undefined
• .env.local 会覆盖 .env，且默认被 Git 忽略 —— 适用于存放本地密钥等敏感信息
• import.meta.env.MODE 的值为 development 或 production —— 可用于条件逻辑判断，不应依赖 NODE_ENV

CommonJS 兼容性

• 默认为纯 ESM 模式 —— CommonJS 包需通过 optimizeDeps.include 显式声明以启用预构建
• Vite 中不支持 require() —— 应使用 import，或借助 module 模块的 createRequire 实现动态引入
• 部分包发布的 ESM 版本存在缺陷 —— 可将其加入 ssr.noExternal 或 optimizeDeps.exclude，交由 Vite 进行转换处理
• 从 CommonJS 包解构命名导出可能失败 —— 建议改用默认导入再解构：import pkg from 'pkg'; const { method } = pkg

依赖预构建

• Vite 在首次运行时会对依赖进行预构建 —— 若修改了依赖包，可删除 node_modules/.vite 强制重建缓存
• 大型依赖会拖慢开发服务器启动速度 —— 对于极少变动的依赖，可添加至 optimizeDeps.include 以启用持久化缓存
• 本地链接的包（如通过 npm link 安装）不会被自动预构建 —— 需手动加入 optimizeDeps.include
• optimizeDeps.force: true 会在每次启动时强制重建 —— 仅建议用于调试，会严重损害开发体验

路径别名

• 需同时在 vite.config.ts 和 tsconfig.json 中配置 —— Vite 使用自身解析逻辑，TypeScript 则依赖 tsconfig.json
• 应使用 path.resolve(__dirname, './src') 而非相对路径 —— 相对路径易受当前工作目录影响而失效
• @/ 别名并非内置 —— 不同于某些框架，需手动配置

// vite.config.ts
resolve: {
  alias: { '@': path.resolve(__dirname, './src') }
}

开发服务器代理

• 代理仅在开发环境下生效 —— 生产环境需配置真实的 CORS 策略或反向代理
• changeOrigin: true 会重写 Host 请求头 —— 多数校验请求来源的 API 均需此配置
• WebSocket 代理需显式设置 ws: true —— HTTP 代理默认不转发 WebSocket 流量
• 尾部斜杠至关重要：/api 可代理 /api/users，而 /api/ 仅匹配 /api//users（注意双斜杠）

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
      rewrite: path => path.replace(/^\/api/, '')
    }
  }
}

静态资源

• public/ 目录下的文件直接映射至站点根路径，不参与构建处理 —— 适用于 favicon、robots.txt 等需保持原始路径的资源
• src/assets/ 目录下的文件会被处理、哈希化，并支持模块导入 —— 推荐用于代码中引用的图片、字体等资源
• 应通过 import 导入资源以获取正确解析后的 URL：import logo from './logo.png' —— 硬编码路径在构建后将失效
• 动态路径请使用 new URL('./img.png', import.meta.url) —— 模板字符串配合变量的方式不可用

构建优化

• 通过 build.rollupOptions.output.manualChunks 实现代码分割 —— 否则所有代码将被打包进单个巨型 bundle
• 使用 rollup-plugin-visualizer 分析构建产物 —— 快速定位意外引入的大体积依赖
• build.target 默认面向现代浏览器 —— 如需兼容旧版浏览器，可设为 'es2015'，但会导致包体积增大
• build.cssCodeSplit: true（默认启用）—— 每个异步 chunk 将生成独立的 CSS 文件

库模式

• 通过 build.lib 构建 npm 包 —— 其配置与应用模式不同
• 将对等依赖（peer dependencies）设为 external —— 避免将 React/Vue 等框架打包进你的库
• 类型定义需单独通过 tsc 生成 —— Vite 不生成 .d.ts 文件
• 同时输出 ESM 和 CJS 格式：formats: ['es', 'cjs'] —— 部分使用者仍需通过 require() 加载

HMR 问题

• 循环导入会导致 HMR 失效 —— 建议重构代码打破循环，或触发整页刷新作为兜底
• HMR 时状态丢失，说明组件未正确接收更新 —— 请检查是否实现了 import.meta.hot.accept()
• 若 CSS 文件被导入到不支持 HMR 的 JS 模块中，CSS 修改将触发整页刷新 —— 应确保 CSS 导入在支持 HMR 的组件内
• server.hmr.overlay: false 会禁用错误覆盖层 —— 适用于自定义错误处理逻辑，但也会掩盖潜在问题

SSR 配置

• ssr.external 用于标记仅限 Node.js 使用的包 —— 防止 SSR 构建时将 node_modules 打包进服务端产物
• ssr.noExternal 强制将指定包打包进 SSR 产物 —— 适用于含浏览器特定导入逻辑的包
• CSS 导入在 SSR 下默认失败 —— 可使用 ?inline 后缀，或通过 css.postcss 配置适配 SSR 场景