Vite 配置速查表
版本unknown 更新日志2025-11-20 GitHubvitejs/vite
340px

📋 配置文件基础 >>>

📝 配置文件命名

// vite.config.js (基础)
vite.config.ts
vite.config.mjs
vite.config.cjs

⚙️ 指定配置文件

# 指定配置文件
vite --config my-config.js

🏗️ 基础配置结构

export default {
  // 配置选项
}
💡 Vite 支持多种配置文件格式，推荐使用 TypeScript 配置文件获得类型提示

🧠 配置智能提示 >>>

📖 JSDoc 类型提示

/** @type {import('vite').UserConfig} */
export default {
  // 配置内容
}

🔧 defineConfig 助手函数

import { defineConfig } from 'vite'
export default defineConfig({
  // 配置内容
})

📘 TypeScript 配置文件

import type { UserConfig } from 'vite'
export default {
  // 配置内容
} satisfies UserConfig
💡 使用 defineConfig 可以获得完整的类型提示和验证

🔄 条件配置 >>>

🎯 基于命令的条件配置

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // 开发环境特定配置
      server: {
        port: 3000
      }
    }
  } else {
    return {
      // 构建环境特定配置
      build: {
        minify: 'terser'
      }
    }
  }
})

🎭 常用条件判断

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  return {
    // 开发环境
    devOnly: command === 'serve',
    // 生产环境构建
    prodBuild: command === 'build' && mode === 'production',
    // SSR 构建
    ssr: isSsrBuild,
    // 预览模式
    preview: isPreview
  }
})
💡 条件配置允许根据不同的构建环境动态调整配置

⚡ 异步配置 >>>

🚀 异步函数配置

export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()
  return {
    // 使用异步数据
    define: {
      __ASYNC_DATA__: JSON.stringify(data)
    }
  }
})
💡 异步配置适用于需要从外部数据源加载配置的场景

🌍 环境变量使用 >>>

📂 加载环境变量

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 基于模式加载环境变量
  const env = loadEnv(mode, process.cwd(), '')

  return {
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
    server: {
      port: env.APP_PORT ? Number(env.APP_PORT) : 5173,
    },
  }
})

🎯 环境变量作用域

export default defineConfig(({ mode }) => {
  // 加载所有环境变量（不限制 VITE_ 前缀）
  const env = loadEnv(mode, process.cwd(), '')

  // 仅加载 VITE_ 前缀的环境变量
  const viteEnv = loadEnv(mode, process.cwd())

  return {
    // 配置内容
  }
})

📋 环境变量文件优先级

.env                # 所有环境
.env.local          # 所有环境，本地优先
.env.[mode]         # 特定模式
.env.[mode].local   # 特定模式，本地优先
💡 客户端只能访问以 VITE_ 开头的环境变量

⚙️ 核心配置选项 >>>

📁 项目配置

export default defineConfig({
  // 项目根目录
  root: './src',
  // 环境变量目录
  envDir: './env',
  // 基础公共路径
  base: '/my-app/',
  // 模式
  mode: 'development',
  // 配置文件目录
  configFile: 'my-vite.config.js',
})

🌐 服务器配置

export default defineConfig({
  server: {
    // 开发服务器端口
    port: 5173,
    // 自动打开浏览器
    open: true,
    // CORS 配置
    cors: true,
    // 代理配置
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^/////////api, '')
      }
    }
  }
})
💡 代理配置特别适合解决开发环境跨域问题

🔨 构建配置 >>>

📦 构建选项

export default defineConfig({
  build: {
    // 输出目录
    outDir: 'dist',
    // 静态资源目录
    assetsDir: 'assets',
    // 压缩方式
    minify: 'terser',
    // 生成 source map
    sourcemap: true,
    // 构建目标
    target: 'es2015',
    // 代码分割
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router']
        }
      }
    }
  }
})

🎯 构建优化

export default defineConfig({
  build: {
    // 减少内存使用
    chunkSizeWarningLimit: 1000,
    rollupOptions: {
      output: {
        // 手动代码分割
        manualChunks(id) {
          if (id.includes('node_modules')) {
            return 'vendor'
          }
        }
      }
    },
    // 并行处理
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true
      }
    }
  }
})
💡 合理的代码分割可以显著提升应用加载性能

🔌 插件配置 >>>

🧩 基础插件使用

import vue from '@vitejs/plugin-vue'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'

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

🛠️ 自定义插件

export default defineConfig({
  plugins: [
    vue(),
    // 自定义插件
    {
      name: 'my-plugin',
      configureServer(server) {
        server.middlewares.use((req, res, next) => {
          // 自定义中间件
          next()
        })
      }
    }
  ]
})
💡 Vite 插件系统基于 Rollup，扩展性强

🔗 路径别名 >>>

📍 基础别名配置

import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '@components': resolve(__dirname, 'src/components'),
      '@utils': resolve(__dirname, 'src/utils')
    }
  }
})

🎯 正则表达式别名

export default defineConfig({
  resolve: {
    alias: [
      {
        find: /^@components/,
        replacement: resolve(__dirname, 'src/components')
      }
    ]
  }
})
💡 路径别名可以简化导入路径，提高代码可维护性

🎨 CSS 配置 >>>

🖌️ 预处理器配置

export default defineConfig({
  css: {
    // CSS 预处理器配置
    preprocessorOptions: {
      scss: {
        additionalData: '@import "@/styles/variables.scss";'
      },
      sass: {
        additionalData: '@use "@/styles/variables" as *;'
      },
      less: {
        javascriptEnabled: true
      }
    }
  }
})

🔧 PostCSS 配置

export default defineConfig({
  css: {
    // PostCSS 配置
    postcss: {
      plugins: [
        require('autoprefixer'),
        require('tailwindcss'),
        require('postcss-nested')
      ]
    }
  }
})

🎯 CSS 模块化

export default defineConfig({
  css: {
    modules: {
      localsConvention: 'camelCaseOnly'
    }
  }
})
💡 CSS 模块化可以帮助避免样式命名冲突

⚡ 依赖优化 >>>

📦 预构建配置

export default defineConfig({
  optimizeDeps: {
    // 强制预构建依赖
    include: ['vue', 'vue-router', 'axios'],
    // 排除预构建
    exclude: ['@tensorflow/tfjs'],
    // 添加需要转换的依赖
    force: true,
    // 自定义 ES 构建选项
    esbuildOptions: {
      target: 'es2020'
    }
  }
})

🚀 开发性能优化

export default defineConfig({
  server: {
    fs: {
      // 限制文件系统访问范围
      strict: false
    },
    hmr: {
      // 热更新配置
      overlay: true
    }
  },
  optimizeDeps: {
    // 预构建优化
    force: true,
    include: ['vue', 'vue-router']
  }
})
💡 合理的依赖优化可以显著提升开发服务器启动速度

📋 常用配置模板 >>>

⚛️ Vue 3 项目

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

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src')
    }
  },
  server: {
    port: 3000,
    open: true
  },
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: false
  }
})

⚛️ React 项目

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

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true
  },
  build: {
    outDir: 'build',
    sourcemap: true
  },
  optimizeDeps: {
    include: ['react', 'react-dom']
  }
})

📘 TypeScript 项目

import { defineConfig } from 'vite'
import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
      '@types': resolve(__dirname, 'src/types')
    }
  },
  server: {
    port: 5173
  },
  build: {
    target: 'esnext',
    outDir: 'dist'
  }
})
💡 根据项目类型选择合适的配置模板可以快速开始开发

🔧 插件开发 >>>

🛠️ 简单插件示例

export default function myPlugin() {
  return {
    name: 'my-plugin',
    // 钩子函数
    config(config, { command }) {
      // 配置钩子
      return {
        // 返回配置合并
      }
    },
    configResolved(resolvedConfig) {
      // 配置解析完成钩子
    },
    configureServer(server) {
      // 服务器配置钩子
      server.middlewares.use((req, res, next) => {
        next()
      })
    },
    transform(code, id) {
      // 代码转换钩子
      if (id.endsWith('.vue')) {
        // 转换 Vue 文件
        return code.replace(/foo/g, 'bar')
      }
    }
  }
}

🎯 插件钩子说明

// 主要插件钩子
{
  name: 'plugin-name',          // 插件名称
  config,                        // 配置解析前
  configResolved,              // 配置解析后
  configureServer,              // 开发服务器配置
  configurePreviewServer,        // 预览服务器配置
  transformIndexHtml,            // HTML 转换
  transform,                    // 代码转换
  buildStart,                  // 构建开始
  buildEnd,                    // 构建结束
  closeBundle                   // 关闭构建
}
💡 Vite 插件基于 Rollup 插件接口，扩展了特定的开发服务器钩子

🚀 高级配置 >>>

🎯 预览配置

export default defineConfig({
  preview: {
    // 预览服务器端口
    port: 4173,
    // 自动打开浏览器
    open: true,
    // 主机名
    host: true
  }
})

🔧 实验性功能

export default defineConfig({
  // 实验性功能
  experimental: {
    // 启用构建优化
    buildTarget: 'esnext',
    // 启用 hmrPartialAccept
    hmrPartialAccept: true
  }
})

📊 Worker 配置

export default defineConfig({
  worker: {
    // Worker 输出格式
    format: 'es',
    // Worker 插件
    plugins: [],
    // Worker 打包配置
    rollupOptions: {}
  }
})
💡 高级配置适用于特定需求和性能优化场景