环境变量使用问题

环境变量基础概念

Vite.js 使用环境变量来管理不同环境下的配置。环境变量是在构建时或运行时注入到应用中的键值对，通常用于存储 API 端点、功能开关等敏感或环境特定的信息。Vite 沿用了 dotenv 的规范，支持 .env 文件加载机制。

环境变量文件通常放置在项目根目录下，命名遵循特定规则：

• .env - 所有环境通用
• .env.development - 开发环境
• .env.production - 生产环境
• .env.local - 本地覆盖（git忽略）

# .env.development
VITE_API_URL=https://dev.api.example.com
VITE_DEBUG_MODE=true

环境变量加载机制

Vite 在启动时会自动加载匹配当前模式的环境变量文件。加载顺序遵循以下规则：

1. .env 基础配置
2. .env.[mode] 模式特定配置
3. .env.[mode].local 本地覆盖配置

开发模式下（vite 命令）默认使用 development 模式，构建时（vite build）默认使用 production 模式。可以通过 --mode 参数指定自定义模式：

vite --mode staging

客户端使用环境变量

只有以 VITE_ 开头的变量才会被 Vite 静态替换并暴露给客户端代码。这是为了防止意外泄露敏感信息。在客户端代码中通过 import.meta.env 对象访问：

// 获取API基础URL
const apiUrl = import.meta.env.VITE_API_URL;

// 判断是否为开发环境
const isDev = import.meta.env.MODE === 'development';

// 获取当前应用运行的基础路径
const baseUrl = import.meta.env.BASE_URL;

TypeScript 类型支持

为了获得更好的类型提示，可以在 src 目录下创建 env.d.ts 文件进行类型声明：

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv
}

构建时替换

Vite 在构建过程中会进行静态替换，这意味着环境变量的值会被直接替换到最终代码中。例如：

// 源代码
console.log(import.meta.env.VITE_API_URL);

// 构建后可能变成
console.log("https://prod.api.example.com");

多环境配置实践

实际项目中通常需要管理多个环境配置。一个推荐的做法是：

1. 创建基础配置文件 .env
2. 为每个环境创建特定文件：
   • .env.development
   • .env.staging
   • .env.production
3. 使用 vite.config.js 动态加载配置

// vite.config.js
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 加载所有环境变量
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    // 配置中使用环境变量
    define: {
      __APP_VERSION__: JSON.stringify(env.VITE_APP_VERSION)
    }
  }
})

环境变量安全注意事项

1. 不要提交敏感信息：确保 .env.local 和包含敏感信息的文件在 .gitignore 中
2. 前缀限制：只有 VITE_ 前缀的变量会暴露给客户端
3. 服务端变量：Node.js 端的环境变量仍通过 process.env 访问
4. 值类型处理：所有环境变量值都会被转换为字符串

# 不安全的做法（变量会暴露给客户端）
API_KEY=12345

# 安全的做法
VITE_PUBLIC_KEY=12345

自定义环境变量前缀

如果需要修改默认的 VITE_ 前缀，可以在配置文件中设置：

// vite.config.js
export default defineConfig({
  envPrefix: 'APP_'  // 现在只有 APP_ 前缀的变量会被暴露
})

环境变量与HTML模板

可以在 index.html 中使用环境变量，Vite 会进行替换：

<title>%VITE_APP_TITLE%</title>

测试环境处理

测试环境（如 Jest）可能需要特殊处理环境变量：

// jest.config.js
module.exports = {
  setupFiles: ['<rootDir>/tests/setupEnv.js']
}

// tests/setupEnv.js
process.env.VITE_API_URL = 'http://test.api.example.com'

环境变量验证

推荐使用 envalid 等库进行环境变量验证：

// src/utils/env.ts
import { cleanEnv, str, bool } from 'envalid'

export const env = cleanEnv(import.meta.env, {
  VITE_API_URL: str(),
  VITE_DEBUG_MODE: bool({ default: false })
})

动态环境变量

某些情况下需要运行时动态设置环境变量：

// 通过URL参数覆盖环境变量
const urlParams = new URLSearchParams(window.location.search)
if (urlParams.has('apiUrl')) {
  import.meta.env.VITE_API_URL = urlParams.get('apiUrl')
}

环境变量与Docker集成

在 Docker 环境中使用时，可以通过 --env-file 参数指定环境变量文件：

FROM node:16
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
CMD ["npm", "run", "dev", "--", "--host"]

启动命令：

docker run --env-file .env.production -p 3000:3000 my-vite-app

环境变量与CI/CD集成

在 CI/CD 流程中，可以通过步骤设置环境变量：

# GitHub Actions 示例
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm run build
      env:
        VITE_API_URL: ${{ secrets.PRODUCTION_API_URL }}

环境变量性能优化

大量环境变量可能影响构建性能，建议：

1. 只暴露必要的变量给客户端
2. 避免在热路径中使用环境变量判断
3. 对于不变的配置，考虑使用普通配置文件

// 不推荐（每次都会读取环境变量）
function getConfig() {
  return import.meta.env.VITE_CONFIG
}

// 推荐（构建时替换为常量）
const CONFIG = import.meta.env.VITE_CONFIG
function getConfig() {
  return CONFIG
}

环境变量调试技巧

调试环境变量问题时可以：

1. 在控制台查看完整环境对象

console.log(import.meta.env)

2. 检查构建后的代码中变量替换情况
3. 使用 Vite 的 --debug 标志查看加载了哪些环境文件

vite --debug

环境变量与SSR

在 SSR 构建中需要注意：

// 服务端入口
import { createServer } from 'vite'

const server = await createServer({
  server: {
    middlewareMode: true
  }
})

// 服务端可以访问 process.env
console.log(process.env.SSR_ONLY_VAR)

环境变量与代理配置

可以在开发服务器代理配置中使用环境变量：

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: import.meta.env.VITE_PROXY_TARGET,
        changeOrigin: true
      }
    }
  }
})

环境变量与功能开关

实现功能开关的常见模式：

// 环境配置
VITE_FEATURE_NEW_DASHBOARD=true

// 代码中使用
if (import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true') {
  renderNewDashboard()
} else {
  renderLegacyDashboard()
}

环境变量与国际化

可以结合环境变量管理多语言配置：

// .env
VITE_DEFAULT_LOCALE=en
VITE_SUPPORTED_LOCALES=en,fr,de

// 代码中使用
const locales = import.meta.env.VITE_SUPPORTED_LOCALES.split(',')