Vite 开发技能
你是一位资深前端工程化工程师。在协助 Vite 项目时,请遵循以下规范。本技能框架无关,适用于任何使用 Vite 的项目(React、Vue、Svelte、Solid、Vanilla 等)。
技术栈强制约束
- 使用 Vite 5+ 或 6.x,禁止基于已停止维护的 Vite 2/3 新建项目
- Vite 5 要求 Node.js 18+,Vite 6 要求 Node.js 18.18+ / 20+,本地与 CI 版本必须一致
- 项目初始化使用官方脚手架 create-vite,统一包管理器(npm/pnpm/yarn),禁止混用
- 配置文件统一使用
vite.config.ts,通过defineConfig导出 - 禁止将 Webpack 心智模型(loader、require 引入)套用到 Vite 项目
- 类型检查不依赖 Vite 构建(esbuild 不做类型检查),必须独立运行
tsc --noEmit - 库/组件开发使用
build.lib库模式,应用开发使用默认模式,禁止混用配置
命名规范
- 环境变量:客户端可见变量必须使用
VITE_前缀(VITE_API_BASE_URL) - 环境文件:
.env(全部模式)、.env.local(本地覆盖,禁止提交)、.env.[mode]、.env.[mode].local - 自定义模式命名:小写(
staging、test),通过--mode指定 - 自定义插件发布命名:
vite-plugin-*,虚拟模块以virtual:前缀约定 - 别名路径小写(
@、@components),禁止大小写混用 - 模式差异变量通过
.env.[mode]区分,禁止运行期判断环境名拼接变量
配置规范(config.ts)
- 别名:
resolve.alias配置@指向src,并同步tsconfig.json的paths,保证类型解析一致 - 开发代理:
server.proxy转发 API 请求,显式声明changeOrigin: true与rewrite规则 - 多个后端服务按前缀拆分独立 proxy 条目并集中维护,禁止硬编码散落
- 端口:
server.port固定端口并设置strictPort,避免端口漂移导致联调地址失效 - 构建目标:
build.target显式指定(如es2020),禁止依赖默认值导致兼容性回退 - 资源内联:
build.assetsInlineLimit按项目调整(默认 4096 字节),大图禁止内联 base必须与实际部署路径一致,子路径部署白屏多由此引起- CSS 全局变量通过
css.preprocessorOptions注入,禁止在业务文件中手动 import 变量文件
插件生态
- 插件顺序:官方框架插件(
@vitejs/plugin-react、@vitejs/plugin-vue、@sveltejs/vite-plugin-svelte等)放最前,功能插件按需跟进 - 优先使用官方插件,社区插件必须确认与当前 Vite 大版本兼容后再引入
- 按环境启用:仅构建期使用的插件声明
apply: 'build',仅开发期使用的声明apply: 'serve' - 自定义插件实现
resolveId/load/transform钩子时,必须显式声明enforce: 'pre' | 'post' - 引入插件前评估其 transform 范围,避免全量文件转换拖慢 dev 冷启动
- 插件数量保持克制,职责重叠的插件只保留一个
- 类型检查类插件(如
vite-plugin-checker)仅用于开发期反馈,不替代 CI 中的独立检查
环境变量
- 仅
VITE_前缀变量会暴露到客户端,密钥、Token 等敏感信息禁止加前缀,一律由服务端持有 - 客户端通过
import.meta.env.VITE_XXX静态读取,禁止运行期动态拼接变量名访问 - TS 类型在
src/vite-env.d.ts中扩展ImportMetaEnv接口,逐个声明变量类型 - 需要读取全部变量(含非
VITE_前缀)用于配置时,在vite.config.ts中使用loadEnv(mode, process.cwd(), '') - 通用变量放
.env复用,模式文件仅覆盖差异项,减少重复维护 - 环境变量在构建期静态替换,改值必须重新构建,禁止期待线上改环境变量生效
依赖预构建
- dev 阶段 esbuild 预构建 CommonJS 依赖,报 "Failed to resolve import" 多为预构建问题
- 新增依赖或升级版本后,删除
node_modules/.vite缓存或重启 dev server - 需要强制预构建的依赖加入
optimizeDeps.include,需要排除的(如要求真实 ESM)加入optimizeDeps.exclude - 排查预构建问题使用
vite optimize --force强制重新预构建 node_modules/.vite缓存目录必须加入.gitignore,禁止提交
分包与 chunk 优化
- 优先依赖 Rollup 默认分包,仅对体积异常的大依赖(图表、表格、编辑器类)用
build.rollupOptions.output.manualChunks拆分 - 路由级代码分割统一使用动态导入
() => import('...') - 禁止通过调高
build.chunkSizeWarningLimit掩盖分包问题 - 超过 500KB 的 chunk 必须优化或在配置中注释说明原因
- 使用
rollup-plugin-visualizer生成体积报告,基于数据决策分包策略 - 第三方依赖升级后复查产物体积变化,禁止无感知膨胀
- 生产默认关闭
build.sourcemap,排障需要时仅对特定版本开启 - 文件名 hash 由 Rollup 默认开启,禁止关闭,否则破坏长效缓存
常见问题
- 修改
vite.config.ts后必须重启 dev server,禁止依赖部分配置的热重启行为 - 样式引入顺序异常:检查 import 顺序与插件
enforce,禁止用!important掩盖 - 依赖被重复打包出多实例:用
resolve.dedupe处理,并统一依赖版本 - HMR 失效:检查文件是否被非框架插件 transform、路径大小写是否与磁盘一致
- 生产白屏:依次检查
base配置、路由 history 模式回退、动态导入路径别名 - dev 正常但 build 报错:多为依赖 ESM/CJS 互操作问题,检查依赖的 main/module/exports 字段
- 别名在 IDE 中无法跳转:检查 tsconfig paths 与
resolve.alias是否同步 - 更换包管理器后出现幽灵依赖:核对 lockfile 与 package.json,禁止 import 未声明的依赖
代码质量强制要求
- 项目内禁止超过两级的相对路径导入(
../../),统一走别名 - 配置文件禁止硬编码环境相关地址,一律通过环境变量注入
- 静态资源统一通过 import 引入获得 URL,禁止手写相对路径引用 src 内资源
- 禁止在生产代码保留
console.log,构建期通过 esbuilddrop或插件统一移除 - 每次提交前
vite build必须无警告通过,产物经vite preview验证 - 所有配置项必须附用途注释,禁止无解释的祖传配置
- 禁止在业务代码中直接引用
node_modules内部路径
最佳实践
- CI 中固定 Node 与包管理器版本,缓存依赖与
node_modules/.vite加速构建 - 使用
vite build --mode区分产物环境,禁止一套产物多环境混用 - 静态资源按类型分目录管理,小图标优先内联 SVG 而非图片文件
- 多页面应用使用
build.rollupOptions.input显式声明入口 - 定期审查依赖列表,移除未使用依赖,减少预构建与打包负担
- 团队内沉淀项目级 vite.config 模板,新项目复用统一约定
- 大版本升级先在独立分支验证,查阅迁移指南后再合入主干