一文了解Vite 与环境变量开发、测试、生产环境切换头大？手把手教你用 Vite 环境变量管理 API 地址、功能开关

一、什么是环境变量？

环境变量是在操作系统或运行环境中定义的键值对，用于配置应用程序的行为。在前端开发中，环境变量常用于存储 API 地址、密钥、功能开关等配置信息，使得代码可以在不同环境中（开发、测试、生产）使用不同的配置。

二、Vite 中环境变量的基本使用

Vite 在设计上提供了一套简单而强大的环境变量机制，帮助开发者在不同环境中管理配置。

环境变量文件约定

Vite 遵循特定的文件命名约定来加载环境变量：

.env：所有环境通用
.env.local：所有环境通用，本地覆盖，通常加入 .gitignore
.env.[mode]：特定模式下的环境变量，如 .env.development、.env.production
.env.[mode].local：特定模式下的本地环境变量，如 .env.development.local

加载优先级从上到下递增，即 .env.[mode].local 中的变量会覆盖其他文件中的同名变量。

环境变量命名规范

为了安全考虑，Vite 只会加载以 VITE_ 为前缀的环境变量到客户端代码中。例如：

# .env 文件
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App

# 不会暴露给客户端的变量
DB_PASSWORD=secret123
API_SECRET=supersecret

只有以 VITE_ 开头的变量才会通过 import.meta.env 在客户端代码中访问。

三、在代码中使用环境变量

访问环境变量

在 Vite 项目中，可以通过 import.meta.env 对象访问环境变量：

// 获取环境变量
const apiUrl = import.meta.env.VITE_API_URL
const appTitle = import.meta.env.VITE_APP_TITLE

// 获取内置环境变量
const mode = import.meta.env.MODE // 当前模式，如 development、production
const dev = import.meta.env.DEV // 是否是开发环境
const prod = import.meta.env.PROD // 是否是生产环境

环境变量的类型

所有通过 import.meta.env 获取的环境变量都是字符串类型，即使是数字或布尔值也需要进行类型转换：

// 错误的做法
const count = import.meta.env.VITE_COUNT // "42" (字符串)
if (count > 10) { /* 这里是字符串比较 */ }

// 正确的做法
const count = Number(import.meta.env.VITE_COUNT) // 42 (数字)
const enabled = import.meta.env.VITE_FEATURE_ENABLED === 'true' // 转换为布尔值

使用环境变量的示例

// src/config/api.js
const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000'

export const apiConfig = {
  baseUrl: API_BASE_URL,
  timeout: Number(import.meta.env.VITE_API_TIMEOUT) || 5000
}

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import { apiConfig } from './config/api'

console.log('API Base URL:', apiConfig.baseUrl)
console.log('Running in', import.meta.env.MODE, 'mode')

createApp(App).mount('#app')

四、不同环境下的配置

开发环境配置

# .env.development
VITE_API_URL=http://localhost:3000/api
VITE_APP_TITLE=Dev App
VITE_DEBUG=true

生产环境配置

# .env.production
VITE_API_URL=https://api.production.com
VITE_APP_TITLE=My Production App
VITE_DEBUG=false

测试环境配置

# .env.test
VITE_API_URL=https://api.test.com
VITE_APP_TITLE=Test App
VITE_DEBUG=true

补充：智能提示支持

为了获得更好的开发体验，可以为环境变量创建类型定义：

// src/env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_DEBUG: string
  // 更多环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

五、环境变量的实际应用场景

1. API 地址配置

// 根据环境使用不同的 API 地址
const API_ENDPOINTS = {
  development: 'http://localhost:3000/api',
  production: 'https://api.myapp.com',
  staging: 'https://staging-api.myapp.com'
}

const getApiUrl = () => {
  return import.meta.env.VITE_API_URL || API_ENDPOINTS.development
}

2. 功能开关

// 根据环境启用/禁用某些功能
const isFeatureEnabled = () => {
  return import.meta.env.VITE_NEW_FEATURE === 'true'
}

if (isFeatureEnabled()) {
  // 启用新功能
  loadNewFeature()
}

3. 日志级别控制

// 控制日志输出级别
const LOG_LEVEL = import.meta.env.VITE_LOG_LEVEL || 'info'

const logger = {
  debug: (...args) => {
    if (LOG_LEVEL === 'debug') console.log('[DEBUG]', ...args)
  },
  info: (...args) => {
    if (['debug', 'info'].includes(LOG_LEVEL)) console.log('[INFO]', ...args)
  }
}

六、安全注意事项

1. 敏感信息保护

不要在环境变量中存储敏感信息如密码、私钥等：

# ❌ 错误做法 - 这些会暴露给客户端
VITE_API_SECRET=secret_key
VITE_DB_PASSWORD=password123

# ✅ 正确做法 - 这些只在服务器端使用
API_SECRET=secret_key
DB_PASSWORD=password123

2. 环境变量验证

在应用启动时验证必要的环境变量：

// src/utils/envValidator.js
const requiredEnvVars = ['VITE_API_URL', 'VITE_APP_TITLE']

export function validateEnvVars() {
  const missingVars = requiredEnvVars.filter(
    varName => !import.meta.env[varName]
  )
  
  if (missingVars.length > 0) {
    throw new Error(
      `Missing required environment variables: ${missingVars.join(', ')}`
    )
  }
}

七、命令行中设置环境变量

除了使用 .env 文件，还可以在命令行中直接设置环境变量：

# 设置环境变量并运行
VITE_API_URL=https://custom-api.com npm run dev

# 或者使用 cross-env (跨平台)
cross-env VITE_API_URL=https://custom-api.com npm run dev

八、自定义环境模式

Vite 默认支持 development、production 和 test 模式，也可以创建自定义模式：

// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "staging": "vite build --mode staging"
  }
}

然后创建对应的环境文件：

# .env.staging
VITE_API_URL=https://staging-api.myapp.com
VITE_APP_TITLE=Staging App

九、优势

Vite 的环境变量机制提供了以下优势：

安全性：只有 VITE_ 前缀的变量才会暴露给客户端
灵活性：支持多种环境和模式配置
易用性：通过简单的文件约定和 import.meta.env 访问
可维护性：清晰的优先级和覆盖机制

结语

合理使用环境变量可以让我们的应用在不同环境中灵活配置，提高开发效率和应用的可维护性。记住始终将敏感信息保存在服务器端环境变量中，而不是客户端可访问的环境变量中。

希望通过本文的讲解，能对你有所帮助，如果本文中有错误或缺漏，请你在评论区指出，大家一起进步，谢谢🙏。

一文了解Vite 与 环境变量