Vite 环境变量使用指南

环境变量文件

项目支持以下环境变量文件：

  • .env - 所有环境下都会加载
  • .env.local - 所有环境下都会加载，但会被 git 忽略
  • .env.[mode] - 只在指定模式下加载（如 .env.development）
  • .env.[mode].local - 只在指定模式下加载，但会被 git 忽略

环境变量命名规则

⚠️ 重要：只有以 VITE_ 开头的变量才会暴露给客户端代码。

# ✅ 正确 - 会暴露给客户端
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My App

# ❌ 错误 - 不会暴露给客户端
API_KEY=secret123
DATABASE_URL=postgres://...

1. 在 vite.config.ts 中使用环境变量

方法一：使用 loadEnv（推荐）

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig(({ mode }) => {
  // 加载环境变量
  // mode: 'development' | 'production' | 'test'
  // process.cwd(): 项目根目录
  // '': 加载所有环境变量（不仅仅是 VITE_ 开头的）
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [vue()],
    server: {
      port: Number(env.VITE_PORT) || 5173,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    },
    define: {
      // 如果需要在代码中使用非 VITE_ 开头的变量
      __APP_VERSION__: JSON.stringify(env.npm_package_version)
    }
  }
})

方法二：使用 import.meta.env（仅限 VITE_ 变量）

import { defineConfig } from 'vite'

export default defineConfig({
  // ❌ 这样不行 - import.meta.env 在配置文件中不可用
  server: {
    port: import.meta.env.VITE_PORT // 错误！
  }
})

2. 在 TypeScript/JavaScript 代码中使用

在 .vue 文件或 .ts 文件中

// ✅ 正确使用方式
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
const appTitle = import.meta.env.VITE_APP_TITLE
const isDev = import.meta.env.DEV  // Vite 内置变量
const isProd = import.meta.env.PROD // Vite 内置变量
const mode = import.meta.env.MODE   // 'development' | 'production'

console.log('API URL:', apiBaseUrl)
console.log('App Title:', appTitle)
console.log('Is Development:', isDev)

在 Vue 组件中

<script setup lang="ts">
const apiUrl = import.meta.env.VITE_API_BASE_URL

console.log('API Base URL:', apiUrl)
</script>

<template>
  <div>
    <h1>{{ import.meta.env.VITE_APP_TITLE }}</h1>
    <p>Environment: {{ import.meta.env.MODE }}</p>
  </div>
</template>

3. TypeScript 类型支持

创建或更新 env.d.ts 文件：

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_ENV: string
  // 更多环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

4. Vite 内置环境变量

Vite 提供了一些内置的环境变量：

import.meta.env.MODE          // 'development' | 'production'
import.meta.env.BASE_URL      // 部署应用时的基本 URL
import.meta.env.PROD          // 是否运行在生产环境
import.meta.env.DEV           // 是否运行在开发环境
import.meta.env.SSR           // 是否运行在服务器端

5. 项目示例

.env 文件

# API 配置
VITE_API_BASE_URL=https://juleon.site/api

# 应用配置
VITE_APP_TITLE=AI Image Generator
VITE_ENV=development

# 服务器配置
VITE_PORT=5173

.env.development 文件

# 开发环境配置
VITE_API_BASE_URL=http://localhost:3000/api
VITE_ENV=development

.env.production 文件

# 生产环境配置
VITE_API_BASE_URL=https://api.production.com
VITE_ENV=production

vite.config.ts

import { fileURLToPath, URL } from 'node:url'
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'

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

  return {
    plugins: [vue()],
    server: {
      port: Number(env.VITE_PORT) || 5173,
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL || 'http://localhost:3000',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '/api/')
        }
      }
    },
    resolve: {
      alias: {
        '@': fileURLToPath(new URL('./src', import.meta.url))
      }
    }
  }
})

在代码中使用

// src/api/request.ts
import axios from 'axios'

const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
  timeout: 60000
})

export default request

6. 常见问题

Q1: 为什么我的环境变量是 undefined？

A: 确保变量名以 VITE_ 开头，并且已经重启了开发服务器。

Q2: 如何在 vite.config.ts 中访问环境变量？

A: 使用 loadEnv 函数：

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  // 现在可以使用 env.VITE_XXX
})

Q3: 环境变量修改后不生效？

A: 需要重启开发服务器：

# 停止服务器 (Ctrl+C)
# 重新启动
npm run dev

Q4: 如何在不同环境使用不同的配置？

A: 创建对应的环境文件：

.env                # 所有环境
.env.development    # 开发环境
.env.production     # 生产环境

然后使用对应的命令：

npm run dev         # 使用 .env.development
npm run build       # 使用 .env.production

Q5: 如何使用非 VITE_ 开头的变量？

A: 在 vite.config.ts 中使用 define 选项：

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    define: {
      __API_KEY__: JSON.stringify(env.API_KEY)
    }
  }
})

然后在代码中使用：

// 需要在 env.d.ts 中声明
declare const __API_KEY__: string

console.log(__API_KEY__)

7. 最佳实践

✅ 推荐做法

  1. 使用 VITE_ 前缀：所有客户端变量都使用 VITE_ 前缀
  2. 类型定义：在 env.d.ts 中定义所有环境变量的类型
  3. 提供默认值：使用 || 提供默认值
  4. 敏感信息：使用 .env.local 存储敏感信息（不提交到 git）
  5. 文档化：在 .env.example 中提供示例配置

❌ 避免做法

  1. 不要在客户端代码中存储敏感信息（API 密钥、密码等）
  2. 不要提交 .env.local 文件到 git
  3. 不要在环境变量中存储大量数据
  4. 不要忘记重启服务器

8. 示例：完整的环境变量配置

.env.example（提交到 git）

# API 配置
VITE_API_BASE_URL=https://api.example.com

# 应用配置
VITE_APP_TITLE=My Application
VITE_APP_VERSION=1.0.0

# 功能开关
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_DEBUG=false

.env.local（不提交到 git）

# 本地开发配置
VITE_API_BASE_URL=http://localhost:3000
VITE_ENABLE_DEBUG=true

.gitignore

# 环境变量
.env.local
.env.*.local

参考资源