Article

前端构建 Vite

更新于：2026-07-10

Vite 完整指南

第 1 章：Vite 简介与快速上手

1.1 什么是 Vite

概念名称说明注意事项
Vite一个现代化的前端构建工具，由 Vue 作者尤雨溪开发，利用浏览器原生 ES 模块导入支持，实现极速的开发服务器启动和热更新。Vite 不依赖打包即可启动开发服务器，适用于现代浏览器环境。
核心定位面向现代浏览器的前端开发工具，主打”极速冷启动”和”按需编译”。不适用于需要支持旧版浏览器（如 IE）的项目开发阶段。
工作模式开发模式下基于原生 ESM 提供模块，生产环境使用 Rollup 打包。开发与生产构建机制不同，需注意配置一致性。

1.2 Vite 的核心优势与原理概述

概念名称说明注意事项
原生 ES 模块（ESM）Vite 在开发时直接利用浏览器对 <script type="module"> 的支持，按需加载模块，无需预先打包整个应用。要求浏览器支持 ES 模块，不兼容 IE。
按需编译只在请求时编译当前所需的模块（如 .vue, .ts, .jsx），避免全量打包。初次访问快，但后续模块加载仍需编译时间（通常毫秒级）。
预构建（Pre-bundling）使用 esbuild 将依赖（如 npm 包）预构建为 ESM 格式，提升加载速度。esbuild 用 Go 编写，比 JS 工具快 10-100 倍。首次启动会触发预构建，之后缓存，可通过 --force 清除。
HMR（热模块替换）修改文件后，仅更新变更模块，不刷新页面，保留应用状态。支持框架级 HMR 插件（如 React Fast Refresh）。

1.3 创建第一个 Vite 项目

方法名称语法用途代码示例注意事项
create-vitenpm create vite@latest初始化一个新的 Vite 项目，交互式选择项目名称、框架、变体（如 React + TypeScript）。npm create vite@latest my-vue-app -- --template vue使用 @latest 确保获取最新版本；--template 可指定模板。
或 yarn create vite
或 pnpm create vite
模板名称vanilla, vue, react, preact, svelte, lit, qwik 等，支持 +ts 后缀启用 TypeScript。快速生成对应技术栈的项目结构。create-vite my-app --template react-ts模板名区分大小写，建议使用官方支持的模板。

1.4 项目结构解析

文件/目录说明注意事项
index.html项目入口 HTML 文件，Vite 从这里开始解析模块。必须存在，可直接引用 ES 模块。
src/源码目录，存放 JavaScript、TypeScript、组件等。可自定义路径，但需在配置中调整。
public/静态资源目录，文件会原样复制到构建输出目录。适合放 favicon.ico、robots.txt 等无需处理的文件。
vite.config.jsVite 配置文件，可导出配置对象或函数。支持 .js, .ts, .mjs 等格式。
package.json包管理文件，包含脚本命令如 dev, build, preview。脚本通常为："dev": "vite"、"build": "vite build"、"preview": "vite preview"
node_modules/依赖包存放目录。预构建依赖在此目录中处理。

第 2 章：开发服务器与热更新

2.1 启动开发服务器（vite dev）

方法名称语法用途代码示例注意事项
vite 或 vite devvite 或 vite dev启动 Vite 开发服务器，默认监听 localhost:5173。vite --port 3000 --openvite 命令等价于 vite dev，可省略 dev。支持参数：--host, --port, --open 等
--host--host 或 --host 0.0.0.0指定服务器应绑定的主机地址，0.0.0.0 允许局域网访问。vite --host若未指定，默认绑定 localhost，仅本机可访问。
--port--port <number>指定服务器端口。vite --port 8080若端口被占用，Vite 会提示并询问是否切换。
--open--open启动后自动打开浏览器。vite --open可指定路径，如 --open /admin。
--https--https启用 HTTPS 服务（需配置证书）。vite --https自签名证书可能触发浏览器安全警告。
--cors--cors启用 CORS 中间件，允许跨域请求。vite --cors适用于前端需被其他域嵌入的场景。

2.2 热模块替换（HMR）机制详解

概念名称说明注意事项
HMR（Hot Module Replacement）当模块代码修改后，Vite 通过 WebSocket 通知浏览器替换模块，无需刷新页面。保持应用状态，提升开发体验。
HMR APIVite 提供全局 import.meta.hot API 用于自定义 HMR 行为。仅在开发模式下存在，生产环境会被树摇掉。
import.meta.hot.accept接受自身或依赖模块的更新。常用于无框架场景或自定义模块处理。
import.meta.hot.dispose在模块被替换前执行清理逻辑。如清除定时器、解绑事件等。
import.meta.hot.invalidate主动使当前模块失效，触发重载。用于依赖外部资源变化的场景。
框架集成React（通过 @vitejs/plugin-react 支持 Fast Refresh）、Vue（SFC 自动支持 HMR）多数框架无需手动处理 HMR。

2.3 服务器配置（server 配置项）

配置项语法类型用途代码示例注意事项
server.hoststring | boolean指定开发服务器绑定的主机地址。server: { host: '0.0.0.0' }true 等价于 '0.0.0.0'，允许外部访问。
server.portnumber设置开发服务器端口。server: { port: 3000 }若被占用，Vite 会自动提示并询问是否更换。
server.openboolean | string启动后是否自动打开浏览器。server: { open: '/dashboard' }string 表示打开的具体路径。
server.httpsboolean | object启用 HTTPS。对象形式可传入证书。server: { https: { key: fs.readFileSync('key.pem'), cert: fs.readFileSync('cert.pem') } }需自行生成或配置证书文件。
server.corsboolean | CorsOptions启用 CORS，支持跨域请求。server: { cors: true }默认允许所有源，生产环境慎用。
server.proxy{ [key: string]: string | ProxyOptions }配置代理，解决开发时跨域问题。server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }changeOrigin 解决主机头不匹配问题。
server.hmrboolean | { clientPort, server, ... }配置 HMR WebSocket 连接行为。server: { hmr: { clientPort: 443, protocol: 'wss' } }用于反向代理或 HTTPS 场景下的 HMR 适配。
server.middlewareModeboolean以中间件模式运行 Vite（用于嵌入其他 Node 服务）。server: { middlewareMode: true }不启动 HTTP 服务器，仅提供中间件函数。

第 3 章：构建与生产优化

3.1 构建项目（vite build）

方法名称语法用途代码示例注意事项
vite buildvite build 或 vite build [root]使用 Rollup 将项目打包为静态资源，用于生产部署。vite build --mode production默认读取 vite.config.js 中的 build 配置。
--mode--mode <mode>指定当前构建的模式（影响环境变量加载）。vite build --mode staging模式决定加载哪个 .env 文件。
--outDir--outDir <dir>指定输出目录。vite build --outDir dist-prod优先级高于配置文件中的 build.outDir。
--sourcemap--sourcemap 或 --sourcemap <type>生成 sourcemap 文件，用于生产调试。vite build --sourcemap inline可选值：true, false, inline, hidden。
--minify--minify 或 --minify <type>启用代码压缩，支持 terser 或 esbuild。vite build --minify terseresbuild 是默认压缩器，更快；terser 压缩更小但慢。
--emptyOutDir--emptyOutDir 或 --no-emptyOutDir构建前清空输出目录。vite build --no-emptyOutDir若输出目录包含重要文件，需谨慎使用。

3.2 预览生产构建（vite preview）

方法名称语法用途代码示例注意事项
vite previewvite preview 或 vite preview --host --port 5000启动一个本地 HTTP 服务器，预览 build 生成的静态文件。vite preview --port 8080 --open必须先运行 vite build 才能预览。
--host--host 或 --host 0.0.0.0指定预览服务器绑定的主机地址。vite preview --host默认仅 localhost 可访问。
--port--port <number>指定预览服务器端口。vite preview --port 3000若端口占用会报错。
--open--open 或 --open /admin启动后自动打开浏览器。vite preview --open用于快速验证构建结果。
--strictPort--strictPort若端口被占用则直接退出，不尝试其他端口。vite preview --strictPort适用于 CI/CD 环境。

3.3 构建配置（build 配置项）

配置项类型用途代码示例注意事项
build.outDirstring指定构建输出目录（相对于项目根目录）。build: { outDir: 'dist' }默认为 dist，可使用绝对路径。
build.assetsDirstring静态资源（如 JS、CSS、图片）的子目录。build: { assetsDir: 'static' }所有非 HTML 资源默认放入此目录。
build.sourcemapboolean | 'inline' | 'hidden'是否生成 sourcemap。build: { sourcemap: true }生产环境建议设为 false 或 hidden 以保护源码。
build.minifyboolean | 'terser' | 'esbuild'是否启用压缩及使用哪种压缩器。build: { minify: 'terser' }terser 支持更多压缩选项但较慢。
build.terserOptionsTerserOptions自定义 Terser 压缩选项（仅当 minify: 'terser' 时生效）。build: { terserOptions: { compress: { drop_console: true } } }可用于删除 console.log。
build.rollupOptionsRollupOptions直接配置底层 Rollup 打包行为。build: { rollupOptions: { input: 'src/main.ts' } }可用于多页面配置、自定义插件等。
build.emptyOutDirboolean构建前是否清空输出目录。build: { emptyOutDir: false }若为 false，旧文件可能残留。
build.chunkSizeWarningLimitnumber设置代码块大小警告阈值（单位 KB）。build: { chunkSizeWarningLimit: 1000 }默认 500KB，超过会警告。

3.4 代码分割与懒加载

概念/方法说明代码示例注意事项
动态导入（Dynamic Import）使用 import() 函数实现按需加载模块，自动触发代码分割。button.addEventListener('click', () => { import('./module.js').then(mod => { /* 使用 mod */ }) })返回 Promise，需异步处理。
Rollup 自动代码分割Vite 使用 Rollup 在生产构建时自动将动态导入的模块拆分为独立 chunk。自动生成 chunk-xxx.js 文件。不需要额外配置，开箱即用。
预加载（preload）Vite 自动为动态导入的模块生成 <link rel="modulepreload">。<link rel="modulepreload" href="/assets/home-xxx.js">提升加载性能，无需手动添加。
预获取（prefetch）对非关键路由模块使用插件实现 prefetch。通常配合路由框架（如 Vue Router）使用。Vite 原生不直接支持 prefetch，需插件或手动插入 <link rel="prefetch">。
手动 chunk 分割通过 rollupOptions.output.manualChunks 自定义 chunk 拆分策略。build: { rollupOptions: { output: { manualChunks: { vendor: ['react', 'react-dom'] } } } }可优化缓存策略，减少重复加载。

第 4 章：环境变量与模式配置

4.1 环境变量的使用

概念名称说明代码示例注意事项
import.meta.envVite 提供的全局环境变量对象，包含所有以 VITE_ 开头的环境变量。const apiURL = import.meta.env.VITE_API_URL、console.log(import.meta.env.MODE)只有 VITE_ 前缀的变量会被暴露到客户端代码。
VITE_ 前缀环境变量必须以 VITE_ 开头才能通过 import.meta.env 访问。.env 中写 VITE_API_BASE=https://api.example.comNODE_ENV, BASE_URL 等非 VITE_ 变量不会暴露。
内置环境变量Vite 自动注入以下变量：MODE（当前模式）、BASE_URL（应用基础路径）、PROD（是否为生产环境）、DEV（是否为开发环境）if (import.meta.env.PROD) { /* 生产逻辑 */ }PROD 和 DEV 是布尔值，便于条件判断。

4.2 模式（mode）与 .env 文件

概念名称说明代码示例注意事项
模式（Mode）Vite 项目运行的上下文环境，如 development, production, staging 等。vite build --mode staging影响 .env 文件加载和构建行为。
.env默认加载的环境变量文件，适用于所有模式。VITE_APP_NAME=MyApp所有模式都会加载。
.env.local本地环境变量文件，不会被提交到版本控制（通常在 .gitignore 中）。VITE_API_KEY=abc123适合存放敏感信息。
.env.[mode]特定模式下的环境变量文件，如 .env.production。.env.staging 中写 VITE_API_URL=https://staging.api.com仅在对应模式下加载。
.env.[mode].local特定模式的本地变量文件，优先级最高。.env.production.local本地覆盖，不提交。
加载优先级文件加载顺序（从低到高）：.env → .env.local → .env.[mode] → .env.[mode].local-同名变量后者覆盖前者。

4.3 自定义环境配置

方法/配置说明代码示例注意事项
自定义模式名称可使用任意字符串作为模式，如 staging, testing。vite build --mode staging模式名决定加载哪个 .env.[mode] 文件。
配置文件中访问模式在 vite.config.js 中可通过 mode 参数区分配置。export default ({ mode }) => { if (mode === 'staging') { return { define: { 'import.meta.env.API_BASE': JSON.stringify('https://staging.api.com') } } } }vite.config.js 支持导出函数，接收 { command, mode } 参数。
define 配置在构建时将变量内联到代码中。define: { __APP_VERSION__: JSON.stringify('1.0.0') }替换发生在编译阶段，不可动态更改。
禁用 .env 文件加载使用 --mode 但不希望加载 .env 文件，可通过配置控制。-通常不建议禁用，可通过 CI 设置环境变量替代。在 CI/CD 中推荐直接设置环境变量而非使用 .env 文件。

第 5 章：插件系统与扩展能力

5.1 Vite 插件机制概述

概念名称说明注意事项
插件机制Vite 插件基于 Rollup 插件接口设计，支持 options, buildStart, resolveId, load, transform 等钩子。插件在配置文件 vite.config.js 中通过 plugins: [] 注册。
钩子执行顺序插件钩子按注册顺序执行，但 pre 类插件优先，post 类插件靠后。可通过 enforce: 'pre' 或 enforce: 'post' 控制执行时机。
开发 vs 构建插件可在开发服务器和构建阶段同时生效，部分钩子仅在构建时调用。如 buildStart 仅在 vite build 时触发。
虚拟模块插件可通过 resolveId + load 提供虚拟模块（如 virtual:env-config）。模块 ID 建议加前缀避免冲突。
插件上下文插件函数接收 viteConfig 对象，可通过 config、command（'build' 或 'serve'）做条件判断。用于区分开发与生产行为。

5.2 常用官方插件介绍（如 @vitejs/plugin-react）

插件名称安装命令用途代码示例注意事项
@vitejs/plugin-reactnpm install @vitejs/plugin-react -D支持 React 项目，启用 JSX 转换和 Fast Refresh。import react from '@vitejs/plugin-react'
export default {
plugins: [react()]
}		必须安装才能使用 .jsx / .tsx 文件。
@vitejs/plugin-vuenpm install @vitejs/plugin-vue -D支持 Vue 3 单文件组件（SFC）。import vue from '@vitejs/plugin-vue'
export default {
plugins: [vue()]
}		配合 vue-tsc 可支持类型检查。
@vitejs/plugin-vue-jsxnpm install @vitejs/plugin-vue-jsx -D支持 Vue 中使用 JSX 语法。import vueJsx from '@vitejs/plugin-vue-jsx'
export default {
plugins: [vue(), vueJsx()]
}		需同时启用 @vitejs/plugin-vue。
@vitejs/plugin-legacynpm install @vitejs/plugin-legacy -D为现代构建生成兼容旧浏览器的降级包（含 polyfill）。import legacy from '@vitejs/plugin-legacy'
export default {
plugins: [legacy()]
}		增加构建体积，仅在需兼容 IE 时使用。
@vitejs/plugin-basic-sslnpm install @vitejs/plugin-basic-ssl -D快速启用 HTTPS（自签名证书），用于开发。import basicSsl from '@vitejs/plugin-basic-ssl'
export default {
plugins: [basicSsl()]
}		浏览器会提示证书不安全，仅用于本地开发。

5.3 自定义插件开发

方法/钩子语法用途代码示例注意事项
插件结构{ name: 'my-plugin', enforce?: 'pre' | 'post', <hook>: () => {} }定义一个插件对象，包含名称和钩子函数。export default function myPlugin() {
return {
name: 'vite-plugin-hello',
configureServer(server) {
server.middlewares.use((req, res, next) => {
console.log(\Request: ${req.url}`)<br> next()<br> })<br> }<br> }<br>}`		name 必须唯一，避免冲突。
configureServerconfigureServer(server)在开发服务器启动时注册中间件或监听事件。见上例仅在 serve 模式下执行。
resolveIdresolveId(id, importer)自定义模块解析逻辑，返回解析后的 ID。resolveId(id) {
if (id === 'virtual:config') {
return '\0virtual:config'
}
}		返回 \0 前缀表示虚拟模块，避免与其他插件冲突。
loadload(id)返回模块的源码内容，配合 resolveId 使用。load(id) {
if (id === '\0virtual:config') {
return \export default { mode: ”${process.env.NODE_ENV}” }`<br> }<br>}`		用于动态生成模块内容。
transformtransform(code, id)对模块源码进行转换（如 Babel 编译、注入代码）。transform(code, id) {
if (id.endsWith('.ts')) {
return babelTransform(code)
}
}		性能敏感，避免全量处理。
buildStartbuildStart()构建开始前执行，可用于初始化资源或检查配置。buildStart() {
console.log('Build started!')
}		仅在 vite build 时调用。

第 6 章：CSS 与静态资源处理

6.1 CSS 导入与模块化

方法/概念语法用途代码示例注意事项
CSS 导入import './style.css'在 JavaScript 中导入 CSS 文件，由 Vite 处理并注入页面。import './assets/index.css'支持相对路径和别名。
全局注入所有导入的 CSS 默认合并到入口 chunk 中，全局生效。自动生成 <style> 标签插入 <head>。不支持按需加载样式块。
构建输出生产构建时 CSS 被提取为独立 .css 文件。输出到 assets 目录，如 style.abc123.css。可通过 build.cssCodeSplit 控制是否拆分。
内联 CSS使用 ?inline 后缀阻止 CSS 提取，内联到 JS 中。import 'bootstrap/dist/css/bootstrap.min.css?inline'适用于需要 JS 动态注入样式的场景。
CSS HMR修改 CSS 文件时，Vite 会替换 <style> 标签内容，无需刷新页面。开箱即用，无需配置。保留 DOM 状态，提升开发体验。

6.2 预处理器支持（Sass/Less/Stylus）

预处理器所需依赖语法代码示例注意事项
Sass/SCSSsass（或 node-sass）@import, @mixin, #{$var} 等import './style.scss'推荐使用 sass（Dart Sass），node-sass 已弃用。
Lessless@import, .mixin(), @variableimport './style.less'需全局安装 less 或项目内安装。
Stylusstylus无大括号/冒号语法，支持缩进import './style.styl'语法灵活，但可读性较低。
自定义选项css.preprocessorOptions传递编译选项，如全局变量、函数路径。css: { preprocessorOptions: { scss: { additionalData: \@import ”@/styles/variables.scss”;` } } }`additionalData 常用于自动导入全局变量文件。

6.3 CSS Modules 与 CSS 变量

概念/方法说明代码示例注意事项
CSS Modules启用局部作用域 CSS，避免样式冲突。文件名以 .module.css 结尾。/* Button.module.css */
.primary { color: blue; }
import styles from './Button.module.css'
console.log(styles.primary) // 哈希类名		类名会被哈希化，确保唯一性。
支持预处理器.module.scss, .module.less 等也支持 CSS Modules。import styles from './Theme.module.scss'同样启用局部作用域。
全局样式使用 :global(...) 包裹选择器可定义全局样式。:global(.global-class) { color: red; }用于需要全局生效的组件或第三方库覆盖。
CSS 变量（自定义属性）原生支持 CSS 变量，可在 JS 中动态修改。:root { --theme-color: blue; }
.box { color: var(--theme-color); }
document.documentElement.style.setProperty('--theme-color', 'red')		推荐用于主题切换等动态场景。
在 JS 中读取变量使用 getComputedStyle 读取当前变量值。const root = getComputedStyle(document.documentElement)
const color = root.getPropertyValue('--theme-color')		适用于需要根据主题做逻辑判断的场景。

6.4 静态资源引用（图片、字体等）

资源类型引用方式用途代码示例注意事项
图片（img）import imgUrl from './image.png'获取资源路径，用于 <img src> 或 CSS 背景。import logo from './logo.png'
document.getElementById('img').src = logo		小于 assetsInlineLimit 会转为 base64。
图片（HTML）<img src="/src/assets/pic.jpg" />直接在 HTML 或模板中引用。路径基于项目根目录或 public/。推荐使用 src 相对路径，Vite 会处理。
字体文件@font-face { src: url('./font.woff2') }导入自定义字体。@font-face {
font-family: 'CustomFont';
src: url('./assets/font.woff2') format('woff2');
}		推荐放在 src/assets 中由 Vite 处理。
public/ 目录/logo.svg放置不需处理的静态资源，路径以 / 直接访问。<img src="/favicon.ico" />文件原样复制，不参与构建处理，无哈希。
资源内联限制build.assetsInlineLimit小于该值（字节）的资源转为 base64 内联。build: { assetsInlineLimit: 4096 }默认 4KB，减少 HTTP 请求。
动态资源加载import() 或 new URL()动态获取资源路径（如音视频、大文件）。const audioUrl = new URL('../assets/sound.mp3', import.meta.url).href推荐用于非关键资源，避免打包过大。

第 7 章：与框架的集成

7.1 集成 React

方法/配置语法用途代码示例注意事项
创建 React 项目npm create vite@latest my-react-app -- --template react快速生成基于 Vite 的 React 项目（JS 版本）。npm create vite@latest my-app -- --template react-ts（TS 版）使用 --template 指定模板。
安装 React 插件npm install @vitejs/plugin-react -D启用 JSX 支持和 React Fast Refresh。import react from '@vitejs/plugin-react'
export default { plugins: [react()] }		必须在 vite.config.js 中注册插件。
JSX 支持.jsx / .tsx 文件自动识别编写 React 组件，支持 JSX 语法。function App() {
return <h1>Hello Vite + React!</h1>
}		不需额外配置，插件自动处理。
Fast Refresh开发时自动启用修改组件时保留状态并热更新。无需手动调用 API。比全页面刷新更高效，提升开发体验。
TypeScript 支持react-ts 模板或手动配置在 React 中使用 TypeScript。create-vite app --template react-ts需确保 tsconfig.json 正确配置。

7.2 集成 Vue 3

方法/配置语法用途代码示例注意事项
创建 Vue 项目npm create vite@latest my-vue-app -- --template vue生成基于 Vite 的 Vue 3 项目。npm create vite@latest my-app -- --template vue-ts支持 TS 模板。
安装 Vue 插件npm install @vitejs/plugin-vue -D支持 .vue 单文件组件（SFC）解析。import vue from '@vitejs/plugin-vue'
export default { plugins: [vue()] }		必须安装并注册插件。
SFC 支持.vue 文件自动解析支持 <template>, <script>, <style> 块。<template>
<div>{{ msg }}</div>
</template>
<script>
export default { data() { return { msg: 'Hello' } } }
</script>		开发时按需编译，构建时打包。
<script setup><script setup> 语法糖简化组合式 API 的使用。<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>		推荐用于 Vue 3 项目，更简洁。
HMR 支持自动启用修改 .vue 文件时热更新组件。无需配置。保留组件状态，开发体验优秀。

7.3 集成 TypeScript

方法/配置语法用途代码示例注意事项
创建 TS 项目--template react-ts, vue-ts 等使用模板快速创建支持 TypeScript 的项目。npm create vite@latest my-app -- --template react-ts推荐方式。
tsconfig.json配置文件定义 TypeScript 编译选项。{ "compilerOptions": { "target": "ES2020", "useDefineForClassFields": true, "module": "ESNext", "moduleResolution": "bundler", "strict": true } }Vite 原生支持 TS，开发时通过 esbuild 快速转译（不校验类型）。
类型检查单独运行 tsc --noEmit执行类型检查，确保代码正确性。在 package.json 中添加："type-check": "tsc --noEmit"建议在 CI/CD 中执行，避免影响开发速度。
vite.config.ts使用 TypeScript 编写配置文件提高配置文件的可维护性和类型安全。import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({ plugins: [react()] })		需安装 typescript，Vite 自动识别 .ts 配置文件。
自定义类型声明env.d.ts 或 global.d.ts扩展全局变量或模块类型。// env.d.ts
interface ImportMetaEnv { readonly VITE_API_URL: string }
interface ImportMeta { readonly env: ImportMetaEnv }		推荐用于补全 import.meta.env 类型。

7.4 集成 Preact / Svelte 等

框架模板命令所需插件用途注意事项
Preactnpm create vite@latest my-preact -- --template preact@preact/preset-vite（已包含在模板中）使用轻量级 React 替代方案。模板已预配置，支持 HMR 和 JSX。
Sveltenpm create vite@latest my-svelte -- --template svelte@sveltejs/vite-plugin-svelte集成 Svelte 组件框架。需在 svelte.config.js 中配置编译选项。
Litnpm create vite@latest my-lit -- --template lit@lit-labs/vite-plugin支持基于 Web Components 的 Lit 框架。适合构建可复用组件库。
SolidJSnpm create vite@latest my-solid -- --template solidsolid-plugins/vite零运行时、高性能的响应式框架。模板已集成插件，开箱即用。
Vanilla + TSnpm create vite@latest my-app -- --template vanilla-ts无需插件纯 JS/TS 项目，适合库开发或轻量应用。可自由集成其他工具。

第 8 章：高级配置与优化技巧

8.1 自定义配置文件（vite.config.js）

配置项类型用途代码示例注意事项
defineConfig函数提供类型提示并安全导出配置。import { defineConfig } from 'vite'
export default defineConfig({
server: { port: 3000 }
})		推荐使用，尤其在 TypeScript 项目中。
导出函数(configEnv) => config根据命令和模式动态返回配置。export default ({ command, mode }) => {
if (command === 'serve') {
return { /* dev config */ }
} else {
return { /* build config */ }
}
}		command 为 'build' 或 'serve'，mode 为当前模式。
条件配置process.env.NODE_ENV === 'development'按环境差异化配置。const isDev = process.env.NODE_ENV === 'development'
export default { base: isDev ? '/' : '/my-app/' }		注意：process.env 在客户端代码中不暴露非 VITE_ 变量。
配置文件格式.js, .ts, .mjs, .cjs支持多种模块格式。vite.config.ts 可使用 TypeScript。.mjs 需设置 "type": "module" 或使用 .mjs 后缀。

8.2 代理配置（Proxy）解决跨域

配置项语法类型用途代码示例注意事项
server.proxy{ [key: string]: ProxyOptions }将 API 请求代理到后端服务器，解决开发跨域。server: {
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}		仅在开发服务器（vite dev）中生效。
targetstring指定代理目标地址。target: 'https://api.example.com'必填项。
changeOriginboolean修改请求头中的 origin 为目标地址。changeOrigin: true解决某些后端服务器的主机名校验问题。
rewrite(path: string) => string重写请求路径。rewrite: (path) => path.replace(/^\/api/, '/v1')常用于去除前缀或将路径映射到不同版本。
secureboolean是否验证 HTTPS 证书。secure: false若代理到自签名 HTTPS 服务，需设为 false。
多路径代理多个前缀分别配置代理多个不同接口路径。proxy: {
'/api': { target: 'http://api.example.com' },
'/upload': { target: 'http://upload.example.com' }
}		避免路径冲突。

8.3 别名（alias）配置

配置项语法类型用途代码示例注意事项
resolve.aliasArray<{ find: string, replacement: string }> | Record<string, string>配置模块路径别名，简化导入。resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
'@components': path.resolve(__dirname, 'src/components')
}
}		建议使用绝对路径。
@ 别名常见约定指向 src/ 目录，减少 ../../ 冗余。import Header from '@/components/Header.vue'需配合 tsconfig.json 中的 paths 保持一致。
tsconfig.json 配置compilerOptions.paths使 TypeScript 正确解析别名。{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }否则编辑器会报错找不到模块。
使用 path 模块path.resolve()生成绝对路径，确保跨平台兼容。path.resolve(__dirname, 'src')在 vite.config.js 中使用。
Vite 2 vs 3+Vite 3+ 支持字符串别名简化配置写法。alias: { '@': './src' }推荐使用 Vite 3+ 新语法。

8.4 公共目录（publicDir）与公共资源

配置项类型用途代码示例注意事项
publicDirstring | false指定静态资源目录，默认 'public'。publicDir: 'static' 或 publicDir: false设为 false 则不使用公共目录。
文件访问方式/ 开头的路径直接通过根路径访问 public 目录下的文件。<img src="/logo.svg" />文件原样复制，不参与构建处理。
适用资源静态文件适合放 favicon.ico, robots.txt, manifest.json、字体、大图片等。public/fonts/Roboto.woff2 → /fonts/Roboto.woff2路径基于项目根目录。
构建输出outDir 下原样复制public 目录内容直接复制到构建输出目录。dist/logo.svg不会进行哈希命名或压缩。
优先级高于静态资源处理若 public 和 src/assets 有同名文件，public 的文件优先。注意命名冲突。建议明确区分用途。
环境相关资源如 env-config.js可在 public 中放置环境相关脚本，运行时加载。<script src="/env-config.js"></script>适用于 CI/CD 注入配置的场景。

第 9 章：部署与最佳实践

9.1 部署构建产物

部署方式说明部署命令/操作注意事项
静态托管服务将 dist/ 目录上传至支持静态文件托管的平台。vite build → 上传 dist 文件夹构建前确保 base 配置正确（如子路径部署需设 base: '/my-app/'）。
Vercel自动识别 Vite 项目，零配置部署。推送代码至 GitHub/GitLab，自动构建部署支持 vite.config.js，默认命令为 vite build。
Netlify支持自定义构建命令和输出目录。构建命令：vite build，发布目录：dist可在 netlify.toml 中配置：publish = "dist"。
GitHub Pages通过 Actions 或本地推送 gh-pages 分支部署。使用 gh-pages 包：npx gh-pages -d dist若部署到子路径，需设置 base 和路由 404.html fallback。
自建服务器（Nginx/Apache）手动将 dist 文件复制到服务器目录。Nginx 配置示例：location / { root /var/www/myapp; try_files $uri $uri/ /index.html; }必须配置 SPA 路由 fallback 到 index.html。
Docker 部署使用轻量镜像托管静态资源。Dockerfile 示例：FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf		适合微服务架构或 CI/CD 流水线。

9.2 CDN 与资源优化

优化策略说明配置方式注意事项
启用 Gzip/Brotli 压缩减小资源体积，提升加载速度。在服务器或 CDN 上启用压缩Vite 构建不直接生成压缩文件，依赖部署层处理。
静态资源托管至 CDN将 JS、CSS、图片等上传至 CDN 加速分发。使用 build.assetsDir 分类资源，配合插件如 vite-plugin-cdn-import可减少主站带宽压力，提升全球访问速度。
设置长期缓存哈希Vite 默认为文件名添加内容哈希，支持长期缓存。build: { rollupOptions: { output: { assetFileNames: 'assets/[name]-[hash][extname]' } } }HTML 文件不应长期缓存，JS/CSS 可设 Cache-Control: max-age=31536000。
预加载关键资源使用 <link rel="modulepreload"> 预加载重要模块。Vite 自动生成 modulepreload可手动添加 <link rel="prefetch"> 预取路由组件。
图片懒加载延迟加载非首屏图片。使用 loading="lazy"：<img src="image.jpg" loading="lazy" />结合 IntersectionObserver 实现更精细控制。

9.3 性能监控与调试技巧

工具/方法用途使用方式注意事项
Chrome DevTools分析加载性能、网络请求、内存使用。打开 Network、Lighthouse 面板关注 First Contentful Paint、Time to Interactive 等指标。
Lighthouse自动化性能审计工具。在 DevTools 中运行或使用 CLI建议定期检查，目标得分 >90。
构建分析插件可视化打包体积。安装 rollup-plugin-visualizer：import { visualizer } from 'rollup-plugin-visualizer'
build: { rollupOptions: { plugins: [visualizer()] } }		构建后生成 stats.html，分析大体积依赖。
build.sourcemap生成 sourcemap 用于生产环境调试。build: { sourcemap: 'hidden' }hidden 不暴露 source，但可在 DevTools 中调试。
错误监控服务捕获线上 JS 错误。集成 Sentry、Bugsnag 等 SDK在 main.js 中初始化错误上报。
HMR 调试查看热更新是否正常触发。修改文件观察控制台日志若 HMR 失败，检查 import.meta.hot 是否被正确处理。

9.4 项目迁移：从 Webpack 到 Vite

迁移步骤说明操作示例注意事项
1. 创建 Vite 配置新建 vite.config.jsimport { defineConfig } from 'vite'
export default defineConfig({
root: 'src',
build: { outDir: '../dist' }
})		逐步迁移，可先保留 Webpack 用于生产。
2. 替换启动命令修改 package.json 脚本"scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }删除 webpack-dev-server 相关脚本。
3. 处理别名与路径配置 resolve.aliasresolve: { alias: { '@': path.resolve(__dirname, 'src') } }同步更新 tsconfig.json 的 paths。
4. 替换 LoaderVite 内置支持大多数格式，无需额外 loader。删除 babel-loader, css-loader 等Babel 配置通过 @vitejs/plugin-react 等插件处理。
5. 代理配置迁移将 Webpack devServer.proxy 转为 Vite server.proxyserver: { proxy: { '/api': 'http://localhost:3000' } }语法基本一致，注意 rewrite 使用。
6. 构建优化调整利用 Vite 的更快构建能力移除 terser-webpack-plugin，使用 build.minify可启用 esbuild 压缩进一步提速。
7. 测试与验证确保功能、路由、静态资源正常。手动测试核心流程注意动态导入、公共路径、环境变量是否正确。

第 10 章：生态系统与社区资源

10.1 Vite 生态概览

生态组成部分说明代表项目
官方插件Vue、React、Preact、Svelte 等框架支持。@vitejs/plugin-vue, @vitejs/plugin-react
构建工具链基于 esbuild 和 Rollup，高性能解析与打包。esbuild（开发）、Rollup（生产）
框架集成Next.js 类工具：Vite + React 可搭配 vite-plugin-ssr 实现 SSR。vite-plugin-ssr, vike
库开发支持支持构建 ES 模块库，天然适合现代前端库。vite build --lib 模式
TypeScript 支持原生支持 .ts, .tsx，快速转译。内置 esbuild 转译，类型检查独立运行
测试工具与 Vitest 深度集成，提供极速单元测试。vitest, @testing-library

10.2 Vite Plugin Market 介绍

资源平台网址说明使用方式
Vite Plugin Searchhttps://vite-plugin-search.netlify.app/社区维护的 Vite 插件搜索引擎。输入关键词查找插件，查看 GitHub 星标和文档。
Vite Awesomehttps://github.com/vitejs/awesome-vite官方推荐的插件、工具、文章合集。浏览分类：Plugins、Integrations、Examples 等。
npmjs.comhttps://www.npmjs.com/search?q=vite-plugin最全的插件来源，支持关键词搜索。搜索 vite-plugin-* 查找相关包。
GitHub Topicshttps://github.com/topics/vite-plugin查看开源 Vite 插件项目。按星标排序，发现高质量项目。
Vite 官方文档插件列表https://vitejs.dev/plugins/官方收录的常用插件链接。优先选择官方推荐或高维护度插件。

10.3 社区工具与模板推荐

工具/模板用途安装/使用方式说明
VitestVite 原生单元测试框架，极速运行。npm install -D vitest，配置 vitest.config.js与 Vite 共享配置，支持 DOM 模拟、HMR 测试。
Storybook + Vite组件开发与文档工具，支持 Vite 作为构建器。npx storybook@latest init → 选择 Vite适合构建设计系统。
vite-plugin-pages基于文件系统的路由生成（类似 Nuxt/Next）。import Pages from 'vite-plugin-pages'
plugins: [Pages()]		自动生成路由配置，支持 Vue/React。
unocss / windicss原子化 CSS 引擎，与 Vite 集成极佳。npm install unocss -D按需生成 CSS，构建极快。
create-vite 模板官方提供的多种技术栈模板。npm create vite@latest my-app -- --template react支持 vanilla, vue, react, preact, svelte, lit, qwik 等。
vitesse功能齐全的 Vite + Vue3 全栈模板。npm create vitesse@latest my-app包含路由、状态管理、图标集、CI/CD 等。
vite-plugin-inspect调试 Vite 插件处理流程。import Inspect from 'vite-plugin-inspect'
plugins: [Inspect()]		访问 /__inspect/ 查看模块解析、转换过程。