知识库

Appearance

Return to top
On this page

Vite 环境变量

Vite 提供了强大的环境变量管理功能，允许您在不同环境（开发、测试、生产等）中使用不同的配置和值。

环境变量基础

环境文件

Vite 会自动加载项目根目录下的环境文件：

  • .env：所有情况下都会加载
  • .env.local：本地覆盖，通常被 git 忽略
  • .env.development：开发环境（vite、vite serve）
  • .env.production：生产环境（vite build、vite preview）
  • .env.test：测试环境（vitest）

环境变量前缀

Vite 只会暴露以 VITE_ 为前缀的环境变量到客户端代码中：

text
# 可以在客户端代码中访问
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App
VITE_VERSION=1.0.0

# 以下变量不会暴露到客户端
DB_PASSWORD=secret
API_KEY=private-key

使用环境变量

在客户端代码中使用

javascript
// 访问环境变量
const apiUrl = import.meta.env.VITE_API_URL
const appTitle = import.meta.env.VITE_APP_TITLE

console.log(`API URL: ${apiUrl}`)
console.log(`App Title: ${appTitle}`)

// 检查当前环境
if (import.meta.env.DEV) {
  // 开发环境代码
  console.log('Running in development mode')
}

if (import.meta.env.PROD) {
  // 生产环境代码
  console.log('Running in production mode')
}

// 检查模式
console.log('Current mode:', import.meta.env.MODE)

可用的内置环境变量

Vite 提供以下内置环境变量：

  • import.meta.env.MODE：当前模式（development、production、test 等）
  • import.meta.env.DEV：是否为开发环境（始终为布尔值）
  • import.meta.env.PROD：是否为生产环境（始终为布尔值）
  • import.meta.env.SSR：是否为服务端渲染（始终为布尔值）

环境文件示例

开发环境文件

.env.development：

text
VITE_API_URL=http://localhost:3000/api
VITE_APP_ENV=development
VITE_DEBUG=true

生产环境文件

.env.production：

text
VITE_API_URL=https://api.myapp.com
VITE_APP_ENV=production
VITE_DEBUG=false

本地覆盖文件

.env.local（添加到 .gitignore）：

text
VITE_API_URL=http://local-api:4000
VITE_APP_TITLE=My App (Local)
# 本地开发用的特殊配置
VITE_LOCAL_FEATURE=true

配置环境变量

自定义环境变量目录

javascript
// vite.config.js
export default {
  envDir: './config'  // 从 ./config 目录加载环境变量
}

这样 Vite 会从 ./config 目录而不是项目根目录加载环境文件。

模式配置

javascript
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  // 根据模式加载不同配置
  const isDev = mode === 'development'
  
  return {
    define: {
      // 在代码中定义全局常量
      __IS_DEV__: isDev,
      __API_URL__: JSON.stringify(
        isDev ? 'http://localhost:3000' : 'https://api.example.com'
      )
    }
  }
})

安全考虑

敏感信息处理

重要：永远不要在环境变量中存储敏感信息（如密码、API 密钥等），因为以 VITE_ 开头的变量会被嵌入到客户端代码中。

text
# ❌ 不安全 - 这些会被嵌入到客户端代码中
VITE_DB_PASSWORD=secret-password
VITE_PRIVATE_API_KEY=private-key

# ✅ 安全 - 这些不会暴露到客户端
DB_PASSWORD=secret-password
PRIVATE_API_KEY=private-key

服务端环境变量

对于敏感信息，应在服务端处理：

javascript
// server.js - 服务端代码
const express = require('express')
const app = express()

app.get('/api/config', (req, res) => {
  // 从服务端环境变量获取敏感信息
  const dbUrl = process.env.DB_URL
  // 安全地处理请求
  res.json({ status: 'ok' })
})

高级用法

条件环境变量

根据条件设置环境变量：

javascript
// vite.config.js
export default {
  define: {
    // 根据环境设置常量
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    '__API_BASE_URL__': JSON.stringify(
      process.env.NODE_ENV === 'production' 
        ? 'https://api.example.com' 
        : 'http://localhost:3000'
    )
  }
}

运行时环境变量

javascript
// utils/config.js
const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'https://api.example.com',
  title: import.meta.env.VITE_APP_TITLE || 'Default Title',
  debug: import.meta.env.VITE_DEBUG === 'true',
  version: import.meta.env.VITE_VERSION || '1.0.0'
}

export default config

环境变量验证

javascript
// utils/env-validator.js
const requiredEnvVars = [
  'VITE_API_URL',
  'VITE_APP_TITLE'
]

const missingEnvVars = requiredEnvVars.filter(
  envVar => !import.meta.env[envVar]
)

if (missingEnvVars.length > 0) {
  console.warn('Missing required environment variables:', missingEnvVars)
}

模式和环境

定义自定义模式

除了默认的 development 和 production 模式，您可以定义自定义模式：

bash
# 使用自定义模式
npm run dev -- --mode staging

创建对应的环境文件：

  • .env.staging
  • .env.staging.local

.env.staging：

text
VITE_API_URL=https://staging-api.example.com
VITE_APP_ENV=staging
VITE_DEBUG=true

模式特定配置

javascript
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  let envConfig = {}
  
  switch (mode) {
    case 'development':
      envConfig = {
        VITE_API_URL: 'http://localhost:3000',
        VITE_DEBUG: 'true'
      }
      break
    case 'staging':
      envConfig = {
        VITE_API_URL: 'https://staging-api.example.com',
        VITE_DEBUG: 'true'
      }
      break
    case 'production':
      envConfig = {
        VITE_API_URL: 'https://api.example.com',
        VITE_DEBUG: 'false'
      }
      break
  }
  
  return {
    define: {
      ...Object.keys(envConfig).reduce((acc, key) => {
        acc[key] = JSON.stringify(envConfig[key])
        return acc
      }, {})
    }
  }
})

实际应用示例

API 配置

javascript
// config/api.js
const apiConfig = {
  baseUrl: import.meta.env.VITE_API_URL,
  timeout: parseInt(import.meta.env.VITE_API_TIMEOUT) || 10000,
  retries: parseInt(import.meta.env.VITE_API_RETRIES) || 3,
  debug: import.meta.env.VITE_DEBUG === 'true'
}

export default apiConfig

功能开关

javascript
// config/features.js
const features = {
  newUI: import.meta.env.VITE_FEATURE_NEW_UI === 'true',
  analytics: import.meta.env.VITE_FEATURE_ANALYTICS === 'true',
  debugMode: import.meta.env.VITE_DEBUG === 'true'
}

export default features

在组件中使用

vue
<template>
  <div>
    <h1>{{ appTitle }}</h1>
    <debug-panel v-if="debugMode" />
  </div>
</template>

<script>
import config from '@/config/api'
import features from '@/config/features'

export default {
  data() {
    return {
      appTitle: import.meta.env.VITE_APP_TITLE || 'Default App',
      debugMode: features.debugMode
    }
  },
  created() {
    console.log('API Base URL:', config.baseUrl)
  }
}
</script>

通过合理使用环境变量，您可以轻松管理不同环境下的配置，提高应用的灵活性和安全性。