---

name: vite-patterns description: Vite 构建工具模式，包括配置、插件、HMR、环境变量、代理设置、SSR、库模式、依赖预打包和构建优化。在使用 vite.config.ts、Vite 插件或基于 Vite 的项目时激活。 origin: ECC

Vite 模式

适用于 Vite 8+ 项目的构建工具和开发服务器模式。涵盖配置、环境变量、代理设置、库模式、依赖预打包和常见生产环境问题。

何时使用

• 配置 vite.config.ts 或 vite.config.js
• 设置环境变量或 .env 文件
• 为 API 后端配置开发服务器代理
• 优化构建输出（代码块、压缩、资源）
• 使用 build.lib 发布库
• 排查依赖预打包或 CJS/ESM 互操作问题
• 调试 HMR、开发服务器或构建错误
• 选择或排序 Vite 插件

工作原理

• 开发模式将源文件作为原生 ESM 提供——不打包。转换按模块请求按需进行，这就是为什么冷启动快且 HMR 精确。
• 构建模式使用 Rolldown（v7+）或 Rollup（v5-v6）将应用打包用于生产，包含 tree-shaking、代码分割和基于 Oxc 的压缩。
• 依赖预打包通过 esbuild 将 CJS/UMD 依赖一次性转换为 ESM，并缓存在 node_modules/.vite 下，后续启动跳过此工作。
• 插件在开发和构建之间共享统一接口——同一个插件对象同时适用于开发服务器的按需转换和生产管线。
• 环境变量在构建时静态内联。VITE_ 前缀的变量成为包中的公共常量；未加前缀的对客户端代码不可见。

示例

配置结构

基本配置

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': new URL('./src', import.meta.url).pathname },
  },
})

条件配置

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ command, mode }) => {
  const env = loadEnv(mode, process.cwd())   // 仅 VITE_ 前缀（安全）

  return {
    plugins: [react()],
    server: command === 'serve' ? { port: 3000 } : undefined,
    define: {
      __API_URL__: JSON.stringify(env.VITE_API_URL),
    },
  }
})

关键配置选项

| 键 | 默认值 | 描述 | |-----|---------|-------------| | root | '.' | 项目根目录（index.html 所在位置） | | base | '/' | 部署资源的公共基础路径 | | envPrefix | 'VITE_' | 客户端暴露的环境变量前缀 | | build.outDir | 'dist' | 输出目录 | | build.minify | 'oxc' | 压缩器（'oxc'、'terser' 或 false） | | build.sourcemap | false | true、'inline' 或 'hidden' |

插件

必备插件

大多数插件需求由少数维护良好的包覆盖。在编写自己的插件之前先使用这些。

| 插件 | 用途 | 何时使用 | |--------|---------|-------------| | @vitejs/plugin-react-swc | 通过 SWC 实现 React HMR + Fast Refresh | React 应用的默认选择（比 Babel 变体更快） | | @vitejs/plugin-react | 通过 Babel 实现 React HMR + Fast Refresh | 仅在需要 Babel 插件时（emotion、MobX 装饰器） | | @vitejs/plugin-vue | Vue 3 SFC 支持 | Vue 应用 | | vite-plugin-checker | 在 worker 线程中运行 tsc + ESLint 并显示 HMR 覆盖层 | 任何 TypeScript 应用 — Vite 在 vite build 期间不进行类型检查 | | vite-tsconfig-paths | 遵循 tsconfig.json 的 paths 别名 | 当你已在 tsconfig.json 中有别名时 | | vite-plugin-dts | 在库模式下生成 .d.ts 文件 | 发布 TypeScript 库 | | vite-plugin-svgr | 将 SVG 导入为 React 组件 | 使用 SVG 作为组件的 React 应用 | | rollup-plugin-visualizer | 包体积树状图/旭日图报告 | 定期的包体积审计（使用 enforce: 'post'） | | vite-plugin-pwa | 零配置 PWA + Workbox | 需要离线能力的应用 |

关键提醒： vite build 会转译但不会进行类型检查。除非添加 vite-plugin-checker 或在 CI 中运行 tsc --noEmit，否则类型错误会静默发布到生产环境。

编写自定义插件

编写自定义插件很少需要——大多数需求由现有插件覆盖。当确实需要时，先在 vite.config.ts 中内联编写，仅在复用时才提取。

// vite.config.ts — 最小内联插件
function myPlugin(): Plugin {
  return {
    name: 'my-plugin',                       // 必需，必须唯一
    enforce: 'pre',                           // 'pre' | 'post'（可选）
    apply: 'build',                           // 'build' | 'serve'（可选）
    transform(code, id) {
      if (!id.endsWith('.custom')) return
      return { code: transformCustom(code), map: null }
    },
  }
}

关键钩子： transform（修改模块内容）