react-vite-best-practices

React + Vite 最佳实践

React 应用的全面性能优化指南，适用于使用 Vite 构建的项目。涵盖 6 个类别中的 23 条规则，涉及构建优化、代码拆分、开发性能、资源处理、环境配置和包分析。

元数据

• 版本： 2.0.0
• 框架： React + Vite
• 规则数量： 6 个类别中的 23 条规则
• 许可证： MIT

适用场景

以下情况请参考这些指南：

• 为 React 项目配置 Vite
• 实现代码拆分和延迟加载
• 优化构建输出和包大小
• 配置开发环境和 HMR
• 处理图像、字体、SVG 和静态资源
• 管理不同环境中的环境变量
• 分析包大小和依赖项

按优先级划分的规则类别

优先级	类别	影响	前缀
1	构建优化	严重	build-
2	代码拆分	严重	split-
3	开发	高	dev-
4	资源处理	高	asset-
5	环境配置	中	env-
6	包分析	中	bundle-

快速参考

1. 构建优化（严重）

• build-manual-chunks - 配置手动分块以分离供应商代码
• build-minification - 使用 OXC（默认）或 Terser 进行压缩
• build-target-modern - 面向现代浏览器（baseline-widely-available）
• build-sourcemaps - 按环境配置源映射
• build-tree-shaking - 使用 ESM 确保正确进行摇树优化
• build-compression - Gzip 和 Brotli 压缩
• build-asset-hashing - 基于内容进行哈希处理，以更新缓存

2. 代码拆分（严重）

• split-route-lazy - 使用 React.lazy() 按路由拆分
• split-suspense-boundaries - 策略性地放置 Suspense 边界
• split-dynamic-imports - 使用动态 import() 加载大型组件
• split-component-lazy - 延迟加载非关键组件
• split-prefetch-hints - 在悬停、空闲或进入视口时预获取分块

3. 开发（高）

• dev-dependency-prebundling - 配置 optimizeDeps 以加快启动速度
• dev-fast-refresh - React Fast Refresh 模式
• dev-hmr-config - HMR 服务配置

4. 资源处理（高）

• asset-image-optimization - 图像优化和延迟加载
• asset-svg-components - 使用 SVGR 将 SVG 作为 React 组件
• asset-fonts - Web 字体加载策略
• asset-public-dir - 公共目录与 JavaScript 导入

5. 环境配置（中）

• env-vite-prefix - 客户端变量使用 VITE_ 前缀
• env-modes - 特定模式的环境文件
• env-sensitive-data - 切勿在客户端代码中暴露机密

6. 包分析（中）

• bundle-visualizer - 使用 rollup-plugin-visualizer 分析包

核心配置

推荐的 vite.config.ts

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

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

  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },

  build: {
    target: 'baseline-widely-available',
    sourcemap: false,
    chunkSizeWarningLimit: 500,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },

  optimizeDeps: {
    include: ['react', 'react-dom'],
  },

  server: {
    port: 3000,
    hmr: {
      overlay: true,
    },
  },
})

按路由拆分代码

import { lazy, Suspense } from 'react'

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

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      {/* Routes here */}
    </Suspense>
  )
}

环境变量

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv
}

使用方法

阅读各条规则文件，了解详细说明和代码示例：

rules/build-manual-chunks.md
rules/split-route-lazy.md
rules/env-vite-prefix.md

参考资料

• Vite 文档
• React 文档
• Rollup 文档

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md