Vite 配置详解与多环境变量管理：defineConfig 全参数实战

import { defineConfig } from 'vite'

// 对象形式
export default defineConfig({
  base: '/',
  plugins: [],
})

// 函数形式：可接收 mode 与 command
export default defineConfig(({ command, mode, isSsrBuild }) => {
  return {
    base: command === 'serve' ? '/' : '/app/',
  }
})

命令行选项 (--port 5173)
  └─> vite.config 中的配置
        └─> 默认值 (合并，不覆盖)

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '~': fileURLToPath(new URL('./src', import.meta.url)),
      // 也可以指向字符串
      'utils': '/src/utils',
      // 精确匹配或子路径匹配
      'react-router-dom': 'react-router-dom/es',
    },
  },
})

export default defineConfig({
  resolve: {
    // 默认扩展名解析顺序
    extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'],
    // 解析 package.json 时的字段优先级（默认 browser -> module -> main）
    mainFields: ['browser', 'module', 'jsnext:main', 'jsnext'],
  },
})

export default defineConfig({
  server: {
    port: 5173,
    host: '0.0.0.0',           // 允许局域网访问
    strictPort: true,          // 端口被占用时不自动递增，直接报错
    open: true,                // 启动自动打开浏览器
    cors: true,                // 开发期跨域
  },
})

export default defineConfig({
  server: {
    proxy: {
      // 将 /api 请求代理到后端
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        // 路径重写：/api/users -> /users
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // WebSocket 代理
      '/ws': {
        target: 'ws://localhost:3000',
        ws: true,
      },
      // 正则匹配
      '/^\/fallback/': {
        target: 'http://localhost:9090',
      },
    },
  },
})

export default defineConfig({
  build: {
    outDir: 'dist',
    assetsDir: 'assets',        // 静态资源目录
    target: 'es2020',           // 构建目标（browserslist 语法）
    minify: 'esbuild',          // 或 'terser'
    sourcemap: true,            // 生产 sourcemap
    chunkSizeWarningLimit: 500, // chunk 大小警告阈值 (kB)
    rollupOptions: {
      output: {
        // 手动分包示例
        manualChunks: {
          'vendor-react': ['react', 'react-dom'],
          'vendor-utils': ['lodash-es'],
        },
      },
    },
  },
})

export default defineConfig({
  // 部署在子路径下必须设置，例如 GitHub Pages 的 /repo/
  base: '/my-app/',
})

base='/my-app/' -> 产物内所有资源引用变为 /my-app/assets/xxx.js
base='./'       -> 相对路径（适合任意目录部署）

export default defineConfig({
  build: {
    // 小于该值的资源转 base64 内联，减少请求数
    assetsInlineLimit: 4096, // 4KB
  },
})

.env 文件 -> 被 Vite 加载（dotenv）-> 暴露到 import.meta.env
                │
                ├─> 前缀 VITE_ 的变量 -> 暴露给客户端代码
                └─> 非 VITE_ 前缀       -> 仅在 vite.config 中可见（loadEnv）

// src/vite-env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_APP_TITLE: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

// 直接使用，构建时被静态替换
const apiBase = import.meta.env.VITE_API_URL

// 需要 TS 类型则先声明
const title: string = import.meta.env.VITE_APP_TITLE

.env                 # 所有环境加载
.env.local           # 所有环境 + 本地覆盖（不入库）
.env.development     # 开发模式
.env.production      # 生产模式
.env.staging         # 需 --mode staging 显式指定
.env.local.development

.env                       # 公共：VITE_APP_NAME=MyApp
.env.development           # VITE_API_URL=http://localhost:8080/api
.env.production            # VITE_API_URL=https://api.example.com
.env.staging               # VITE_API_URL=https://staging-api.example.com
.env.local                 # 本地调试覆盖（gitignored）

# 开发（默认 development）
npm run dev

# 以 staging 模式构建
vite build --mode staging

# 构建时注入的环境变量在代码中被替换
# dist 内 VITE_API_URL=https://staging-api.example.com

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  // 此处可读取任意前缀变量（默认前缀 VITE_）
  return {
    define: {
      // 把非 VITE_ 前缀的变量注入到客户端
      __APP_VERSION__: JSON.stringify(env.VERSION),
    },
  }
})

import { defineConfig } from 'vite'

export default defineConfig(({ command, mode }) => {
  const isProd = mode === 'production'

  return {
    define: {
      // 生产才启用某些全局
      __DEV__: JSON.stringify(!isProd),
    },
    plugins: [
      // 根据环境启用不同插件
      isProd ? productionPlugin() : devPlugin(),
    ],
    build: {
      sourcemap: !isProd, // 生产关闭 sourcemap
    },
  }
})

// 临时打印完整 env
console.log(loadEnv(mode, process.cwd(), ''))

// 查看最终解析配置
npx vite --debug

vite --debug | grep proxy

resolve(怎么找文件) -> server(怎么开发) -> build(怎么发布) -> env(怎么区分环境)