---
description: Vite 构建配置和优化
globs: ["**/vite.config.*", "**/package.json", "**/tsconfig.json"]
alwaysApply: false
---

# Vite 构建配置规范

## ⚡ 基础配置

### vite.config.ts 标准配置
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { resolve } from 'path';

export default defineConfig({
  plugins: [vue()],
  
  // ✅ 路径别名配置
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '@components': resolve(__dirname, 'src/components'),
      '@composables': resolve(__dirname, 'src/composables'),
      '@utils': resolve(__dirname, 'src/utils'),
      '@types': resolve(__dirname, 'src/types'),
    },
  },
  
  // ✅ 开发服务器配置
  server: {
    port: 3000,
    host: true,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
  
  // ✅ 构建配置
  build: {
    outDir: 'dist',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router', 'pinia'],
          ui: ['@radix-ui/vue', '@headlessui/vue'],
        },
      },
    },
  },
});
```

## 📦 代码分割策略

### 手动分包配置
```typescript
// ✅ 高级代码分割配置
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        // ✅ 手动分包策略
        manualChunks: (id) => {
          // Vue 相关
          if (id.includes('vue') || id.includes('@vue')) {
            return 'vue';
          }
          
          // UI 组件库
          if (id.includes('@radix-ui') || id.includes('@headlessui')) {
            return 'ui';
          }
          
          // 工具库
          if (id.includes('lodash') || id.includes('dayjs')) {
            return 'utils';
          }
          
          // 第三方库
          if (id.includes('node_modules')) {
            return 'vendor';
          }
        },
        
        // ✅ 文件命名策略
        chunkFileNames: 'assets/js/[name]-[hash].js',
        entryFileNames: 'assets/js/[name]-[hash].js',
        assetFileNames: (assetInfo) => {
          const info = assetInfo.name.split('.');
          const ext = info[info.length - 1];
          if (/\.(mp4|webm|ogg|mp3|wav|flac|aac)(\?.*)?$/i.test(assetInfo.name)) {
            return `assets/media/[name]-[hash].${ext}`;
          }
          if (/\.(png|jpe?g|gif|svg)(\?.*)?$/i.test(assetInfo.name)) {
            return `assets/images/[name]-[hash].${ext}`;
          }
          if (/\.(woff2?|eot|ttf|otf)(\?.*)?$/i.test(assetInfo.name)) {
            return `assets/fonts/[name]-[hash].${ext}`;
          }
          return `assets/[ext]/[name]-[hash].${ext}`;
        },
      },
    },
  },
});
```

## 🔧 环境变量配置

### 环境变量类型定义
```typescript
// src/types/env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_NAME: string;
  readonly VITE_APP_VERSION: string;
  readonly VITE_ENABLE_DEVTOOLS: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

// ✅ 环境变量验证
const validateEnv = () => {
  const requiredVars = ['VITE_API_URL', 'VITE_APP_NAME'];
  const missingVars = requiredVars.filter(
    varName => !import.meta.env[varName]
  );
  
  if (missingVars.length > 0) {
    throw new Error(`缺少必需的环境变量: ${missingVars.join(', ')}`);
  }
};

// ✅ 开发环境配置
if (import.meta.env.DEV) {
  validateEnv();
}
```

## 📊 构建优化

### 性能预算配置
```typescript
// ✅ 性能预算配置
const performanceBudget = {
  // Core Web Vitals
  lcp: 2500,  // 最大内容绘制 < 2.5s
  fid: 100,   // 首次输入延迟 < 100ms
  cls: 0.1,   // 累积布局偏移 < 0.1
  
  // 其他指标
  fcp: 1800,  // 首次内容绘制 < 1.8s
  ttfb: 600,  // 首字节时间 < 600ms
  
  // 资源大小
  jsSize: 250000,  // JS 文件 < 250KB
  cssSize: 50000,  // CSS 文件 < 50KB
  imageSize: 1000000, // 图片 < 1MB
};

// ✅ 构建分析插件
import { visualizer } from 'rollup-plugin-visualizer';

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

## 🎯 构建最佳实践

### 必需配置项
- ✅ 启用 sourcemap 用于调试
- ✅ 配置路径别名简化导入
- ✅ 设置代码分割减少包体积
- ✅ 配置环境变量验证
- ✅ 启用构建分析工具

### 参考文件
- `vite.config.ts` - 主配置文件
- `package.json` - 依赖和脚本配置
- `tsconfig.json` - TypeScript 配置
- `.env.example` - 环境变量模板