17.1 Vite 深度配置

Vite 已经成为 React 项目的主流构建工具，它利用浏览器原生 ES 模块实现极速冷启动，同时基于 Rollup 进行生产打包，兼顾开发体验与构建质量。掌握 Vite 的深度配置，能让你的项目在效率、体积和灵活性上达到最优。

路径别名：告别 `../../../` 地狱

在大型项目中，相对路径引用会变得极其混乱。通过路径别名，可以将特定的目录映射为简短的标识符。

vite.config.js 配置：

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

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),          // @ 指向 src
      '@components': path.resolve(__dirname, 'src/components'),
      '@utils': path.resolve(__dirname, 'src/utils'),
      '@assets': path.resolve(__dirname, 'src/assets'),
    }
  }
});

配合 TypeScript，需要在 tsconfig.json 中添加对应映射，使编辑器能够正确识别：

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

使用效果：

// 之前
import Button from '../../../components/Button';

// 之后
import Button from '@components/Button';

路径别名减少了路径推算的心智负担，也避免了移动文件时必须修改导入路径的问题。

环境变量：多场景配置隔离

Vite 使用 dotenv 加载环境变量，支持 .env、.env.development、.env.production 等文件。只有以 VITE_ 开头的变量才会暴露给客户端代码。

环境文件示例：

# .env.development
VITE_API_BASE_URL=http://localhost:3001/api
VITE_APP_TITLE=开发环境

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=生产环境

在代码中访问：

const apiUrl = import.meta.env.VITE_API_BASE_URL; // 在不同环境自动切换

TypeScript 智能提示：在 src/vite-env.d.ts 中扩展类型定义：

/// <reference types="vite/client" />

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

这样输入 import.meta.env. 时就能自动补全，避免拼写错误。

代理配置：解决开发阶段跨域问题

在开发服务器中配置代理，将特定请求转发到后端服务，绕过浏览器的同源策略。

vite.config.js 示例：

export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',  // 后端地址
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')  // 可选：去掉 /api 前缀
      },
      '/uploads': {
        target: 'http://cdn.example.com',
        changeOrigin: true
      }
    }
  }
});

前端请求 fetch('/api/users') 会被代理到 http://localhost:8080/users，仿佛在同源下请求，避免了开发阶段的 CORS 问题。生产环境部署时，通常由 Nginx 等反向代理处理，配置结构类似。

插件体系：扩展 Vite 能力边界

Vite 插件基于 Rollup 插件接口扩展，同时提供独有的钩子。React 项目最常用的插件是 @vitejs/plugin-react，但实际项目中你可能会用到更多：

常用插件示例：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';
import compression from 'vite-plugin-compression';

export default defineConfig({
  plugins: [
    react({
      // 启用更快的 Babel 编译（可选）
      babel: {
        plugins: ['@emotion/babel-plugin']  // 如使用 Emotion
      }
    }),
    
    // 生成打包分析报告
    visualizer({
      open: true,
      gzipSize: true,
      brotliSize: true
    }),
    
    // 开启 Gzip 压缩（生产环境）
    compression({
      algorithm: 'gzip',
      ext: '.gz',
      threshold: 10240  // 大于 10KB 才压缩
    })
  ]
});

@vitejs/plugin-react：提供 React Fast Refresh、自动 JSX 运行时等能力。
rollup-plugin-visualizer：生成可视化的打包体积分析图，帮助定位大模块。
vite-plugin-compression：构建时生成 .gz 文件，配合 Nginx 实现静态资源预压缩，提升加载速度。

更多插件可查阅 Vite 官方插件列表。

按需加载：组件库体积优化

使用大型组件库（如 Ant Design、Material UI）时，如果不做处理会将整个库打包，体积惊人。Vite 可以通过插件或配置实现按需引入。

以 Ant Design 为例（v5 已自带 tree-shaking，但较低版本需按需加载）：

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

export default defineConfig({
  plugins: [
    react(),
    // 若使用 Antd v4，可配合 vite-plugin-imp 实现按需引入
    // vite-plugin-imp 已不推荐，建议升级到支持 ES modules 的组件库版本
  ],
  // 组件库若支持 ES modules，并在 package.json 中有 module 字段，Vite 天然支持 tree-shaking
});

对于不支持 tree-shaking 的库，可以手动引入所需模块：

import Button from 'antd/es/button';  // 只引入 Button 及其依赖
import 'antd/es/button/style/css';    // 按需引入样式

更好的方案是使用支持 ES Modules 的现代组件库（如 Ant Design v5、Arco Design、Radix UI），Vite 在开发和打包时自然进行 tree-shaking，无需额外配置。

打包优化：控制构建产物与性能

Rollup 提供了丰富的构建配置，可用来优化生产包。

1. 代码分割

将第三方依赖（如 React、React Router、各类工具库）拆分为独立的 chunk，利用浏览器缓存，减少后续访问的加载量。

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
          'ui-lib': ['antd', '@ant-design/icons'],
          'utils': ['lodash-es', 'dayjs']
        }
      }
    }
  }
});

手动分包策略应根据项目实际依赖图和访问模式调整。若不手动指定，Rollup 也会自动拆分为合理粒度，但手动控制能让缓存命中率更高。

2. 资源内联与文件大小限制

export default defineConfig({
  build: {
    // 小于 10KB 的资源转为 base64 内联，减少 HTTP 请求
    assetsInlineLimit: 10240,
    
    // 输出目录
    outDir: 'dist',
    
    // 静态资源分类存放
    assetsDir: 'assets',
    
    // chunk 大小警告阈值（默认 500KB）
    chunkSizeWarningLimit: 1000,
  }
});

3. 压缩配置

Vite 使用 esbuild 进行代码压缩（速度极快），也可以通过 build.minify 指定为 'terser' 来获得更细粒度的控制：

export default defineConfig({
  build: {
    minify: 'terser',  // 'esbuild' 或 false
    terserOptions: {
      compress: {
        drop_console: true,      // 去除 console
        drop_debugger: true      // 去除 debugger
      }
    }
  }
});

drop_console 在生产环境有助于清除调试代码，但要谨慎使用，某些关键错误日志也可能被移除。

4. CSS 处理

Vite 自动处理 CSS Modules、Sass/Less 编译、PostCSS 等。可在 css 字段配置：

export default defineConfig({
  css: {
    // CSS Modules 行为配置
    modules: {
      localsConvention: 'camelCaseOnly',  // 类名驼峰化
    },
    // 预处理器全局变量
    preprocessorOptions: {
      scss: {
        additionalData: `@import "@/styles/variables.scss";`  // 自动注入变量
      }
    },
    postcss: './postcss.config.js'  // 自定义 PostCSS 配置（如 autoprefixer）
  }
});

生产环境构建产物检查

运行 vite build 后，可以使用 vite preview 在本地预览生产产物，验证资源加载、路由是否正常。

# 构建
npm run build

# 本地预览 dist
npx vite preview --port 5000

此外，利用前文提到的 rollup-plugin-visualizer 可以对打包结果进行可视化分析，辅助定位过大的依赖，持续优化。

Vite 的深度配置远不止这些，但以上点覆盖了日常开发中最常用的优化和工程化场景。合理运用这些配置，你的 React 项目将拥有极快的开发体验和优异的生产性能。

路径别名：告别 ../../../ 地狱