vite.config.ts.ftl（Vite 项目配置模板参考示例）

✅ vite.config.ts.ftl 模板文件 —— Vite 项目配置模板

强烈推荐创建此模板文件！Vite 配置是现代前端项目的核心基础设施，直接影响 开发体验、构建性能、安全性和部署灵活性。通过模板自动生成标准化配置，可确保团队项目配置一致性，避免重复配置错误，提升工程化水平。

---

📋 为什么需要 vite.config.ts.ftl？

问题	手动配置风险	模板生成优势
配置重复	每个项目都要重写基础配置	一次定义，处处生成
环境差异	开发/测试/生产环境配置混乱	自动适配环境变量
安全漏洞	忘记配置安全头、CSP 策略	集成安全最佳实践
性能问题	未优化构建配置	自动生成性能优化配置
维护困难	配置分散、文档缺失	集中管理，注释完整

💡 核心价值：标准化 + 安全性 + 性能优化 + 环境适配

---

📄 详细说明文档

1. 配置架构设计

2. 关键功能覆盖

• ✅ 基础配置：项目信息、路径别名、环境变量
• ✅ 开发体验：代理、HTTPS、热更新
• ✅ 构建优化：代码分割、压缩、Tree Shaking
• ✅ 安全加固：CSP、安全头、敏感信息过滤
• ✅ 监控分析：包体积分析、性能监控
• ✅ 环境适配：开发/测试/生产差异化配置

3. 企业级最佳实践

• 🌐 环境变量管理：.env 文件分级管理
• 🔒 安全配置：Content Security Policy、安全响应头
• ⚡ 性能优化：预加载、代码分割、资源压缩
• 📊 监控集成：包体积分析、错误监控
• 🚀 部署友好：静态资源 CDN、缓存策略

---

📝 具有实际开发参考意义的示例

import { defineConfig, loadEnv, ConfigEnv, UserConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vueJsx from '@vitejs/plugin-vue-jsx';
import { createHtmlPlugin } from 'vite-plugin-html';
import { visualizer } from 'rollup-plugin-visualizer';
import { compression } from 'vite-plugin-compression';
import { resolve } from 'path';

/**
 * Vite 项目配置
 *
 * 【设计目标】
 * 1. 提供标准化的项目配置模板
 * 2. 集成企业级安全和性能最佳实践
 * 3. 支持多环境差异化配置
 * 4. 优化开发体验和构建性能
 *
 * 【配置原则】
 * - 环境变量驱动：通过 .env 文件管理配置
 * - 安全优先：集成 CSP、安全头等防护措施
 * - 性能优化：代码分割、压缩、预加载
 * - 可维护性：详细注释，模块化配置
 *
 * @author ${author}
 * @since ${date}
 */
export default defineConfig(({ mode }: ConfigEnv): UserConfig => {
  // 加载环境变量（.env.${mode}）
  const env = loadEnv(mode, process.cwd());
  
  return {
    // ==================== 基础配置 ====================
    
    /**
     * 项目根目录
     * 
     * <p>
     * 【说明】
     * - 默认为当前工作目录
     * - 通常不需要修改
     * </p>
     */
    root: process.cwd(),
    
    /**
     * 项目元信息
     * 
     * <p>
     * 【用途】
     * - 生成 package.json 中的 name/version
     * - HTML 模板中使用
     * </p>
     */
    define: {
      __APP_NAME__: JSON.stringify(env.VITE_APP_NAME || '${projectName}'),
      __APP_VERSION__: JSON.stringify(env.VITE_APP_VERSION || '1.0.0'),
      __BUILD_TIME__: JSON.stringify(new Date().toISOString())
    },
    
    /**
     * 路径别名配置
     * 
     * <p>
     * 【最佳实践】
     * - @ 指向 src 目录
     * - ~ 指向 public 目录（静态资源）
     * - 避免相对路径 ../../../../../
     * </p>
     * 
     * <p>
     * 【使用示例】
     * import MyComponent from '@/components/MyComponent.vue';
     * </p>
     */
    resolve: {
      alias: {
        '@': resolve(__dirname, 'src'),
        '~': resolve(__dirname, 'public')
      },
      // 强制解析为浏览器版本（避免 Node.js 模块）
      mainFields: ['module', 'jsnext:main', 'jsnext'],
      // 扩展名自动补全
      extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue']
    },
    
    /**
     * CSS 配置
     * 
     * <p>
     * 【预处理器】
     * - 支持 Sass/SCSS、Less、Stylus
     * - 自动注入全局变量文件
     * </p>
     */
    css: {
      preprocessorOptions: {
        scss: {
          // 全局 SCSS 变量（无需在每个文件中 @import）
          additionalData: `@use "@/styles/variables.scss" as *;`
        }
      },
      // PostCSS 配置（自动添加浏览器前缀）
      postcss: {
        plugins: [
          require('autoprefixer')({
            overrideBrowserslist: [
              '> 1%',
              'last 2 versions',
              'not dead',
              'iOS >= 10',
              'Android >= 5'
            ]
          })
        ]
      }
    },
    
    // ==================== 开发服务器配置 ====================
    
    /**
     * 本地开发服务器配置
     * 
     * <p>
     * 【关键配置】
     * - host: 0.0.0.0 允许局域网访问
     * - port: 开发端口（可被 .env 覆盖）
     * - open: 自动打开浏览器
     * - proxy: API 代理配置
     * </p>
     */
    server: {
      // 允许局域网访问（移动端调试）
      host: '0.0.0.0',
      // 开发端口
      port: Number(env.VITE_PORT) || 3000,
      // 自动打开浏览器
      open: true,
      // 严格端口检查（端口被占用时退出）
      strictPort: true,
      // HTTPS 支持（开发环境调试 HTTPS API）
      https: env.VITE_HTTPS === 'true',
      // API 代理配置（解决跨域问题）
      proxy: {
        // 代理所有 /api 开头的请求
        '/api': {
          target: env.VITE_API_TARGET || 'http://localhost:8080',
          changeOrigin: true,
          // 重写路径（移除 /api 前缀）
          rewrite: (path) => path.replace(/^\/api/, ''),
          // 开发环境日志
          configure: (proxy, options) => {
            if (env.VITE_PROXY_LOG === 'true') {
              console.log('🚀 [Proxy]', options.target + options.path);
            }
          }
        }
      },
      // 文件监听配置（解决大项目监听文件过多问题）
      watch: {
        ignored: ['**/node_modules/**', '**/dist/**']
      }
    },
    
    // ==================== 构建配置 ====================
    
    /**
     * 构建配置
     * 
     * <p>
     * 【输出目录】
     * - 默认为 dist
     * - 可通过 .env 覆盖
     * </p>
     */
    build: {
      // 输出目录
      outDir: env.VITE_BUILD_OUT_DIR || 'dist',
      // 静态资源输出目录
      assetsDir: 'assets',
      // 生成 sourcemap（生产环境建议关闭）
      sourcemap: mode === 'development',
      // 报告未压缩的包体积
      reportCompressedSize: true,
      // 禁用 minify（调试时使用）
      minify: env.VITE_BUILD_MINIFY !== 'false',
      // 代码分割配置
      rollupOptions: {
        output: {
          // 静态资源文件名（带 hash）
          assetFileNames: (assetInfo) => {
            let extType = assetInfo.name?.split('.').at(-1);
            if (/png|jpe?g|gif|svg|webp/.test(extType!)) {
              extType = 'img';
            }
            return `assets/${extType}/[name]-[hash][extname]`;
          },
          // 代码分割（按路由拆分）
          chunkFileNames: (chunkInfo) => {
            const facadeModuleId = chunkInfo.facadeModuleId ?
              chunkInfo.facadeModuleId.split('/').at(-2) :
              'unknown';
            return `js/${facadeModuleId}/[name]-[hash].js`;
          },
          // 入口文件
          entryFileNames: 'js/[name]-[hash].js'
        }
      },
      // 预加载策略
      dynamicImportVarsOptions: {
        // 预加载动态导入的模块
        exclude: [/node_modules/]
      },
      // 目标浏览器（影响代码转译）
      target: 'es2015',
      // 启用 CSS 代码分割
      cssCodeSplit: true,
      // 启用 brotli 压缩（需要额外插件）
      brotliSize: false
    },
    
    // ==================== 插件配置 ====================
    
    /**
     * Vite 插件配置
     * 
     * <p>
     * 【插件说明】
     * - @vitejs/plugin-vue: Vue 3 支持
     * - @vitejs/plugin-vue-jsx: Vue JSX 支持
     * - vite-plugin-html: HTML 模板注入
     * - vite-plugin-compression: Gzip/Brotli 压缩
     * - rollup-plugin-visualizer: 包体积分析
     * </p>
     */
    plugins: [
      // Vue 3 支持
      vue(),
      
      // Vue JSX 支持（可选）
      vueJsx(),
      
      // HTML 模板注入（注入环境变量到 HTML）
      createHtmlPlugin({
        inject: {
          data: {
            title: env.VITE_APP_TITLE || '${projectName}',
            description: env.VITE_APP_DESCRIPTION || '${projectName} 管理系统',
            // 注入 CSP nonce（如果启用 CSP）
            cspNonce: env.VITE_CSP_NONCE || ''
          }
        }
      }),
      
      // Gzip 压缩（生产环境）
      ...(mode === 'production' ? [compression({
        algorithm: 'gzip',
        threshold: 10240, // 大于 10KB 的文件才压缩
        deleteOriginFile: false // 保留原始文件
      })] : []),
      
      // 包体积分析（仅在分析模式下启用）
      ...(env.VITE_ANALYZE === 'true' ? [visualizer({
        open: true,
        gzipSize: true,
        brotliSize: true,
        filename: 'stats.html'
      })] : [])
    ],
    
    // ==================== 安全配置 ====================
    
    /**
     * 安全相关配置
     * 
     * <p>
     * 【Content Security Policy】
     * - 开发环境：宽松策略
     * - 生产环境：严格策略
     * </p>
     * 
     * <p>
     * 【安全响应头】
     * - 通过 nginx 或中间件设置
     * - Vite 开发服务器不支持设置响应头
     * </p>
     */
    // 注意：CSP 通常在 HTML meta 标签或服务器响应头中设置
    // 此处仅提供配置参考
    ...(env.VITE_CSP_ENABLED === 'true' ? {
      // CSP 配置（需要配合 HTML 模板）
      define: {
        __CSP_POLICY__: JSON.stringify(
          mode === 'development' 
            ? "default-src 'self' 'unsafe-inline' 'unsafe-eval';"
            : "default-src 'self'; script-src 'self' 'nonce-${cspNonce}'; style-src 'self' 'unsafe-inline';"
        )
      }
    } : {}),
    
    // ==================== 其他配置 ====================
    
    /**
     * 预加载配置
     * 
     * <p>
     * 【用途】
     * - 预加载关键资源
     * - 提升首屏加载速度
     * </p>
     */
    optimizeDeps: {
      // 预构建依赖（提升冷启动速度）
      include: [
        'vue',
        'vue-router',
        'pinia',
        'element-plus',
        'axios',
        'lodash-es'
      ],
      // 排除不需要预构建的依赖
      exclude: [
        // 大型库或按需加载的库
      ]
    },
    
    /**
     * 日志级别
     * 
     * <p>
     * 【选项】
     * - info: 默认
     * - warn: 仅警告
     * - error: 仅错误
     * - silent: 无日志
     * </p>
     */
    logLevel: env.VITE_LOG_LEVEL || 'info',
    
    /**
     * 清除控制台日志
     * 
     * <p>
     * 【用途】
     * - 生产环境构建时清除 console.log
     * - 需要额外插件支持
     * </p>
     */
    ...(mode === 'production' && env.VITE_DROP_CONSOLE === 'true' ? {
      esbuild: {
        drop: ['console', 'debugger']
      }
    } : {})
  };
});

---

🔍 关键设计说明

1. 环境变量驱动配置

• .env 文件分级：
  • .env：通用配置
  • .env.development：开发环境
  • .env.production：生产环境
• 配置覆盖顺序：.env.${mode} > .env

2. 安全加固策略

• Content Security Policy (CSP)：
  • 开发环境：宽松策略（支持热更新）
  • 生产环境：严格策略（防止 XSS）
• 安全响应头：
  • 通过 Nginx 设置（X-Frame-Options、X-Content-Type-Options 等）
• 敏感信息过滤：
  • 构建时移除 console.log（可选）

3. 性能优化措施

• 代码分割：按路由和模块拆分
• 资源压缩：Gzip/Brotli 压缩
• 预加载：关键资源预加载
• Tree Shaking：自动移除未使用代码

4. 开发体验优化

• API 代理：解决跨域问题
• HTTPS 支持：调试 HTTPS API
• 局域网访问：移动端调试
• 自动打开浏览器：提升开发效率

5. 监控与分析

• 包体积分析：rollup-plugin-visualizer
• 构建报告：压缩前后体积对比
• 错误监控：集成 Sentry 等（需额外配置）

---

🛠️ 配套环境变量文件示例

.env

# 通用配置
VITE_APP_NAME=${projectName}
VITE_APP_VERSION=1.0.0
VITE_PORT=3000
VITE_LOG_LEVEL=info

.env.development

# 开发环境配置
VITE_API_TARGET=http://localhost:8080
VITE_PROXY_LOG=true
VITE_HTTPS=false
VITE_CSP_ENABLED=false

.env.production

# 生产环境配置
VITE_API_TARGET=https://api.yourdomain.com
VITE_BUILD_OUT_DIR=dist
VITE_BUILD_MINIFY=true
VITE_CSP_ENABLED=true
VITE_CSP_NONCE=${randomNonce}
VITE_DROP_CONSOLE=true
VITE_ANALYZE=false

---

📝 使用说明

1. 生成配置文件

# 通过代码生成器生成
mybatis-plus-generator --template vite.config.ts.ftl

2. 自定义配置

• 修改 .env 文件覆盖默认配置
• 在模板中添加 <!-- CUSTOM CODE START --> 区域进行扩展

3. 分析包体积

# 生成包体积分析报告
VITE_ANALYZE=true npm run build

4. 生产构建

# 标准生产构建
npm run build

# 调试构建（不压缩）
VITE_BUILD_MINIFY=false npm run build

---

✅ 此模板文件是 现代前端项目的基础设施，正确配置后可：

• 提升开发体验：热更新、代理、HTTPS 支持
• 优化构建性能：代码分割、压缩、Tree Shaking
• 增强系统安全：CSP、安全头、敏感信息过滤
• 降低维护成本：标准化配置，团队一致性

可直接用于企业级项目，是高质量前端工程的必备组件。