vite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vite

Overview

概述

Vite is a next-generation frontend build tool that provides instant dev server start via native ES modules and optimized production builds via Rollup. It supports TypeScript, JSX, CSS preprocessors, and static assets out of the box with zero configuration.

When to use: Single-page apps, multi-page apps, library publishing, SSR applications, monorepo packages, any modern frontend project needing fast dev feedback and optimized builds.

When NOT to use: Legacy browsers requiring ES5 output without transpilation, projects locked to Webpack-specific loaders with no Vite equivalents, non-JavaScript build pipelines.

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

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

不适用场景： 需要ES5输出且无需转译的旧版浏览器项目、依赖Webpack特定加载器且无Vite替代方案的项目、非JavaScript构建流水线的项目。

Quick Reference

快速参考

Pattern	API	Key Points
Config file	`defineConfig({})`	Type-safe config with IDE support
Conditional config	`defineConfig(({ command, mode }) => ({}))`	Different config per command/mode
Path alias	`resolve.alias`	Map `@/` to `src/`
Dev proxy	`server.proxy`	Forward API requests to backend
HMR config	`server.hmr`	WebSocket host/port/protocol
HTTPS dev	`server.https`	Pass TLS cert/key options
Build target	`build.target`	ES module target for output
Manual chunks	`build.rollupOptions.output.manualChunks`	Control code splitting
Library mode	`build.lib`	Publish ES/CJS/UMD packages
SSR build	`build.ssr` + `ssr` options	Server-side rendering config
Env variables	`import.meta.env.VITE_*`	Client-exposed env vars
loadEnv	`loadEnv(mode, root, prefix)`	Load env vars in config
CSS modules	`css.modules`	Scoped CSS class names
Preprocessors	`css.preprocessorOptions`	Sass/Less/Stylus options
PostCSS	`css.postcss`	Inline or external PostCSS config
Static assets	`import url from './img.png'`	Returns resolved public URL
Plugin	`{ name, transform, load }`	Hook-based plugin system
Virtual module	`resolveId` + `load` hooks	Generate modules at build time
Multi-page	`build.rollupOptions.input`	Multiple HTML entry points

模式	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 Modules	`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入口文件

Common Mistakes

常见错误

Mistake	Correct Pattern
Exposing secrets via `VITE_` prefix	Only prefix client-safe vars with `VITE_` ; use `loadEnv` in config for server-only secrets
Using `process.env` in client code	Use `import.meta.env.VITE_*` (Vite replaces at build time)
Modifying `rollupOptions.input` without `resolve()`	Always use `path.resolve()` or `import.meta.dirname` for absolute paths
Not externalizing peer deps in library mode	Add React/Vue to `rollupOptions.external` to avoid bundling
Creating QueryClient-style singletons in SSR	Ensure per-request state in SSR to avoid cross-request leaks
Inline PostCSS config alongside `postcss.config.js`	Use one or the other; inline config disables config file search
Setting `base` without trailing slash	`base` should be `/path/` with trailing slash or full URL
Using `__dirname` in ESM config	Use `import.meta.dirname` (Node 21+) or `fileURLToPath`

错误内容	正确做法
通过 `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`

Delegation

任务委托

Plugin discovery: Use
```
Explore
```
agent
Build analysis: Use
```
Task
```
agent
Config review: Delegate to
```
code-reviewer
```
agent

If the
vitest-testing
skill is available, delegate test configuration and Vitest setup to it. If the
tailwind
skill is available, delegate Tailwind CSS configuration and utility patterns to it. If the
react-patterns
skill is available, delegate React component patterns and hooks to it. If the
typescript-patterns
skill is available, delegate TypeScript configuration and type patterns to it. If the
pnpm-workspace
skill is available, delegate monorepo workspace configuration to it.

插件探索：使用
```
Explore
```
Agent
构建分析：使用
```
Task
```
Agent
配置审核：委托给
```
code-reviewer
```
Agent

如果
vitest-testing
技能可用，将测试配置和Vitest设置委托给它。如果
tailwind
技能可用，将Tailwind CSS配置和工具类模式委托给它。如果
react-patterns
技能可用，将React组件模式和Hooks委托给它。如果
typescript-patterns
技能可用，将TypeScript配置和类型模式委托给它。如果
pnpm-workspace
技能可用，将单仓库多包（monorepo）工作区配置委托给它。

References

参考资料

Configuration fundamentals and defineConfig patterns
Plugin authoring and popular plugins
Dev server setup: proxy, HMR, HTTPS, and middleware
Build optimization: chunking, tree-shaking, and output control
Library mode for publishing packages
SSR configuration and Express integration
Environment variables and .env file handling
CSS handling: PostCSS, CSS modules, preprocessors, and asset management

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