Vite 5 项目构建与性能优化完全指南 2026：从入门到生产级配置

# 使用 npm
npm create vite@latest

# 使用 pnpm（推荐）
pnpm create vite

# 使用 yarn
yarn create vite

pnpm create vite my-react-app --template react-ts

{
  "scripts": {
    "dev": "vite",            # 启动开发服务器
    "build": "tsc && vite build",  # 生产构建
    "preview": "vite preview",     # 预览生产构建
    "optimize": "vite optimize"    # 预构建依赖
  }
}

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

export default defineConfig({
  plugins: [react()],
  
  // 开发服务器配置
  server: {
    port: 3000,
    open: true,
    host: true,
    cors: true,
  },
  
  // 构建配置
  build: {
    outDir: 'dist',
    sourcemap: true,
    minify: 'esbuild',
    target: 'es2020',
  },
  
  // 路径别名
  resolve: {
    alias: {
      '@': '/src',
      '@components': '/src/components',
      '@utils': '/src/utils',
    },
  },
});

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils'),
      '@hooks': path.resolve(__dirname, './src/hooks'),
      '@types': path.resolve(__dirname, './src/types'),
    },
  },
});

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@hooks/*": ["src/hooks/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

// .env
VITE_APP_TITLE = My App
VITE_API_URL = https://api.example.com

// 代码中使用
console.log(import.meta.env.VITE_APP_TITLE);
console.log(import.meta.env.VITE_API_URL);

// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string;
  readonly VITE_API_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      // 简单代理
      '/api': 'http://localhost:3001',
      
      // 带选项的代理
      '/api2': {
        target: 'http://localhost:3002',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api2/, ''),
      },
      
      // WebSocket 代理
      '/ws': {
        target: 'ws://localhost:3003',
        ws: true,
      },
    },
  },
});

import { defineConfig } from 'vite';
import imagemin from 'vite-plugin-imagemin';

export default defineConfig({
  plugins: [
    imagemin({
      gifsicle: { optimizationLevel: 7, interlaced: false },
      optipng: { optimizationLevel: 7 },
      mozjpeg: { quality: 80 },
      pngquant: { quality: [0.8, 0.9] },
      svgo: {
        plugins: [
          { name: 'removeViewBox', active: false },
        ],
      },
    }),
  ],
});

import { defineConfig } from 'vite';
import viteCompression from 'vite-plugin-compression';

export default defineConfig({
  plugins: [
    viteCompression({
      verbose: true,
      disable: false,
      threshold: 10240, // 10KB 以上的文件才压缩
      algorithm: 'gzip',
      ext: '.gz',
    }),
    // Brotli 压缩（压缩率更高）
    viteCompression({
      verbose: true,
      threshold: 10240,
      algorithm: 'brotliCompress',
      ext: '.br',
    }),
  ],
});

import { defineConfig } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    visualizer({
      open: true,
      filename: 'dist/stats.html',
      gzipSize: true,
      brotliSize: true,
    }),
  ],
});

import { defineConfig } from 'vite';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: [
        'react',
        'react-router-dom',
        {
          'react-i18next': ['useTranslation', 't'],
        },
      ],
      dts: 'src/auto-imports.d.ts',
      eslintrc: {
        enabled: true,
      },
    }),
  ],
});

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    // 强制预构建依赖
    include: [
      'react',
      'react-dom',
      'react-router-dom',
      'axios',
      'lodash-es',
    ],
    // 排除预构建（让 ESM 包直接被浏览器加载）
    exclude: ['some-esm-only-package'],
    // 预构建时的 esbuild 配置
    esbuildOptions: {
      target: 'es2020',
    },
  },
});

// vite.config.ts
export default defineConfig({
  server: {
    // 启用 HTTP/2（需要证书）
    https: false,
    
    // 预热常用文件，减少首次加载时间
    warmup: {
      clientFiles: ['./src/main.tsx', './src/App.tsx'],
    },
    
    // 文件系统监听配置
    watch: {
      usePolling: true, // Docker/WSL 环境需要
      interval: 1000,
    },
  },
});

// vite.config.ts
export default defineConfig({
  css: {
    // CSS Modules 配置
    modules: {
      localsConvention: 'camelCase',
      generateScopedName: '[name]__[local]___[hash:base64:5]',
    },
    
    // PostCSS 配置
    postcss: {
      plugins: [
        // Autoprefixer（自动加前缀）
        require('autoprefixer'),
        // CSS 嵌套
        require('postcss-nesting'),
      ],
    },
    
    // 预处理器配置
    preprocessorOptions: {
      scss: {
        additionalData: `
          @import "@/styles/variables.scss";
          @import "@/styles/mixins.scss";
        `,
      },
      less: {
        javascriptEnabled: true,
        modifyVars: {
          'primary-color': '#1890ff',
        },
      },
    },
  },
});

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

export default defineConfig({
  plugins: [react()],
});

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
    },
  },
  plugins: [],
};

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

// vite.config.ts
export default defineConfig({
  build: {
    // 输出目录
    outDir: 'dist',
    assetsDir: 'assets',
    
    // 目标浏览器
    target: 'es2020',
    
    // 压缩方式：esbuild（快）| terser（压缩率更高，但慢）
    minify: 'esbuild',
    
    // 生成 source map
    sourcemap: false, // 生产环境关闭
    
    // 代码分割策略
    rollupOptions: {
      output: {
        // 手动分包
        manualChunks: {
          // React 相关
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
          // UI 库
          'antd-vendor': ['antd', '@ant-design/icons'],
          // 工具库
          'utils-vendor': ['lodash-es', 'dayjs', 'axios'],
        },
        
        // 静态资源文件名
        assetFileNames: 'assets/[name].[hash][extname]',
        chunkFileNames: 'assets/[name].[hash].js',
        entryFileNames: 'assets/[name].[hash].js',
      },
    },
    
    // 大于此大小的 chunk 会警告
    chunkSizeWarningLimit: 500, // KB
    
    // 构建时清空目录
    emptyOutDir: true,
    
    // 启用 CSS 代码分割
    cssCodeSplit: true,
  },
});

// 使用 React.lazy + Suspense
import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<Loading />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // 框架核心
          framework: ['react', 'react-dom', 'react-router-dom'],
          
          // UI 组件库
          ui: ['antd', '@ant-design/icons'],
          
          // 数据请求
          data: ['axios', 'react-query'],
          
          // 图表
          charts: ['echarts', 'react-echarts'],
          
          // 富文本编辑器
          editor: ['@tiptap/react', '@tiptap/starter-kit'],
        },
      },
    },
  },
});

import { defineConfig } from 'vite';
import { chunkSplitPlugin } from 'vite-plugin-chunk-split';

export default defineConfig({
  plugins: [
    chunkSplitPlugin({
      strategy: 'default',
      customSplitting: {
        'react-vendor': [/react/, /react-dom/],
        'antd-vendor': [/antd/],
        'utils-vendor': [/lodash/, /dayjs/],
      },
    }),
  ],
});

// 使用 vite-plugin-imagemin
import imagemin from 'vite-plugin-imagemin';

export default defineConfig({
  plugins: [
    imagemin({
      // 只在生产环境启用
      ...(process.env.NODE_ENV === 'production'
        ? {
            gifsicle: { optimizationLevel: 7 },
            optipng: { optimizationLevel: 7 },
            mozjpeg: { quality: 80 },
            pngquant: { quality: [0.8, 0.9] },
            svgo: { plugins: [{ name: 'removeViewBox', active: false }] },
          }
        : {}),
    }),
  ],
});

/* 使用 font-display: swap 避免阻塞渲染 */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter.woff2') format('woff2');
  font-display: swap;
}

// 使用 vite-plugin-svgr 导入 SVG 为组件
import Logo from '@/assets/logo.svg?react';

function Header() {
  return <Logo className="w-6 h-6" />;
}

// ✅ 好：使用具名导出（可以被 Tree Shaking）
export const foo = () => {
  console.log('foo');
};

export const bar = () => {
  console.log('bar');
};

// ❌ 不好：使用默认导出对象（无法被 Tree Shaking）
export default {
  foo: () => console.log('foo'),
  bar: () => console.log('bar'),
};

{
  "sideEffects": [
    "*.css",
    "*.scss",
    "src/polyfill.js"
  ]
}

# 安装
pnpm add -D rollup-plugin-visualizer

// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    visualizer({
      open: true,
      filename: 'dist/stats.html',
      gzipSize: true,
      brotliSize: true,
      template: 'treemap', // treemap | sunburst | network
    }),
  ],
});

# 构建并生成分析报告
pnpm build
# 自动打开 stats.html

# 手动运行预构建
vite optimize --force

# 查看预构建缓存位置
# macOS: ~/Library/Caches/vite
# Linux: ~/.cache/vite
# Windows: %TEMP%/vite

// vite.config.ts
export default defineConfig({
  server: {
    hmr: {
      // 减少 HMR 日志
      overlay: true,
    },
  },
  
  // 优化依赖预构建
  optimizeDeps: {
    include: [
      // 把常用依赖加入预构建
      'react',
      'react-dom',
      'antd',
      'axios',
    ],
  },
});

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

export default defineConfig(({ mode }) => {
  // 加载环境变量
  const env = loadEnv(mode, process.cwd(), '');
  
  return {
    plugins: [react()],
    
    server: {
      port: parseInt(env.VITE_PORT || '3000'),
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
        },
      },
    },
    
    build: {
      sourcemap: mode !== 'production',
      minify: mode === 'production' ? 'esbuild' : false,
    },
  };
});

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

export default defineConfig({
  plugins: [react()],
  
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, 'index.html'),
        admin: resolve(__dirname, 'admin/index.html'),
        docs: resolve(__dirname, 'docs/index.html'),
      },
    },
  },
});

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

export default defineConfig({
  plugins: [react()],
  
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyLib',
      formats: ['es', 'umd', 'cjs'],
      fileName: (format) => `my-lib.${format}.js`,
    },
    
    rollupOptions: {
      // 外部化依赖（不打包进库）
      external: ['react', 'react-dom'],
      output: {
        // UMD 格式的全局变量
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
  },
});

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

export default defineConfig({
  plugins: [react()],
  
  ssr: {
    // 不打包的依赖（保持 require）
    external: ['some-cjs-only-package'],
    // 强制打包的依赖
    noExternal: ['some-esm-package'],
  },
});

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    // 把大依赖加入预构建
    include: ['antd', 'lodash', 'echarts'],
  },
  
  server: {
    // 预热常用文件
    warmup: {
      clientFiles: ['./src/main.tsx', './src/App.tsx'],
    },
    
    // WSL/Docker 环境
    watch: {
      usePolling: true,
    },
  },
});

# 开启调试日志
DEBUG=vite:hmr vite dev

// 部署在子路径时需要配置 base
export default defineConfig({
  base: '/my-app/',
});