vite

Vite

概述

Vite 是新一代前端构建工具，可通过原生 ES 模块即时启动开发服务器，并通过 Rollup 优化生产构建。它开箱即支持 TypeScript、JSX、CSS 预处理器和静态资源，无需配置。

适用场景： 单页应用、多页应用、库发布、SSR 应用、monorepo 包，以及任何需要快速开发反馈和优化构建的现代前端项目。

不适用场景： 需要未经转译即可输出 ES5 的旧版浏览器、被锁定为使用没有 Vite 对应方案的 Webpack 专用 loader 的项目，以及非 JavaScript 构建流程。

快速参考

模式	API	要点
配置文件	defineConfig({})	类型安全的配置，支持 IDE
条件配置	defineConfig(({ command, mode }) => ({}))	按命令/模式使用不同配置
路径别名	resolve.alias	将 @/ 映射到 src/
开发代理	server.proxy	将 API 请求转发到后端
HMR 配置	server.hmr	WebSocket 主机/端口/协议
HTTPS 开发	server.https	传入 TLS 证书/密钥选项
构建目标	build.target	输出的 ES 模块目标
手动分块	build.rollupOptions.output.manualChunks	控制代码拆分
库模式	build.lib	发布 ES/CJS/UMD 包
SSR 构建	build.ssr + ssr 选项	服务端渲染配置
环境变量	import.meta.env.VITE_*	暴露给客户端的环境变量
loadEnv	loadEnv(mode, root, prefix)	在配置中加载环境变量
CSS 模块	css.modules	作用域限定的 CSS 类名
预处理器	css.preprocessorOptions	Sass/Less/Stylus 选项
PostCSS	css.postcss	内联或外部 PostCSS 配置
静态资源	import url from './img.png'	返回解析后的公共 URL
插件	{ name, transform, load }	基于钩子的插件系统
虚拟模块	resolveId + load 钩子	在构建时生成模块
多页应用	build.rollupOptions.input	多个 HTML 入口点

常见错误

错误	正确做法
通过 VITE_ 前缀暴露机密信息	仅为可在客户端安全使用的变量添加 VITE_ 前缀；在配置中使用 loadEnv 处理仅供服务端使用的机密信息
在客户端代码中使用 process.env	使用 import.meta.env.VITE_*（Vite 会在构建时替换）
修改 rollupOptions.input 时未使用 resolve()	始终使用 path.resolve() 或 import.meta.dirname 获取绝对路径
在库模式下未将 peer 依赖标记为外部依赖	将 React/Vue 添加到 rollupOptions.external，以避免打包
在 SSR 中创建 QueryClient 式的单例	确保 SSR 中每个请求的状态相互独立，避免请求间数据泄露
同时使用内联 PostCSS 配置和 postcss.config.js	二选一；内联配置会禁用配置文件搜索
设置 base 时未添加尾随斜杠	base 应设置为带尾随斜杠的 /path/ 或完整 URL
在 ESM 配置中使用 __dirname	使用 import.meta.dirname（Node 21+）或 fileURLToPath

委派

• 插件发现：使用 Explore Agent
• 构建分析：使用 Task Agent
• 配置审查：委派给 code-reviewer Agent

如果有 vitest-testing 技能，请将测试配置和 Vitest 设置委派给它。 如果有 tailwind 技能，请将 Tailwind CSS 配置和实用类模式委派给它。 如果有 react-patterns 技能，请将 React 组件模式和 hooks 委派给它。 如果有 typescript-patterns 技能，请将 TypeScript 配置和类型模式委派给它。 如果有 pnpm-workspace 技能，请将 monorepo 工作区配置委派给它。

参考资料

• 配置基础知识和 defineConfig 模式
• 插件编写和热门插件
• 开发服务设置：代理、HMR、HTTPS 和中间件
• 构建优化：分块、tree-shaking 和输出控制
• 用于发布软件包的库模式
• SSR 配置和 Express 集成
• 环境变量和 .env 文件处理
• CSS 处理：PostCSS、CSS 模块、预处理器和资源管理