环境变量在 Vite 中的使用

问题描述

许多开发者在 Vite 项目中尝试使用环境变量时遇到问题。例如，在 .env 文件中定义了环境变量：

TEST_VAR=123F

但在代码中使用 import.meta.env.TEST_VAR 访问时却返回 undefined。这通常是由于对 Vite 环境变量机制的误解造成的。

解决方案

1. 使用正确的变量前缀

Vite 默认只暴露以 VITE_ 为前缀的环境变量到客户端代码。这是为了防止意外泄露敏感信息。

安全提示

Vite 的这种设计是有意的安全措施，避免将所有环境变量暴露给客户端。

将你的 .env 文件改为：

VITE_TEST_VAR=123F

然后在代码中访问：

console.log(import.meta.env.VITE_TEST_VAR); // 输出 "123F"

2. 自定义环境变量前缀

如果你不想使用 VITE_ 前缀，可以在 vite.config.js 中配置自定义前缀：

export default defineConfig({
  envPrefix: 'TEST_', // 现在可以使用 TEST_ 前缀
  // 其他配置...
})

重要限制

不能将 envPrefix 设置为空字符串 ''，这会暴露所有环境变量，导致敏感信息泄露。

3. 在 Vite 配置文件中访问环境变量

如果需要在 vite.config.js 中访问环境变量，需要使用 loadEnv() 函数：

import { defineConfig, loadEnv } from 'vite'

export default ({ mode }) => {
  // 加载环境变量
  const env = loadEnv(mode, process.cwd())
  
  return defineConfig({
    // 使用 env.VARIABLE_NAME 访问变量
    define: {
      __API_URL__: JSON.stringify(env.VITE_API_URL)
    }
  })
}

4. 处理特殊需求的高级配置

如果需要在客户端代码中使用没有前缀的变量名，可以使用以下配置：

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  
  const processEnv = Object.keys(env).reduce((acc, key) => {
    acc[key] = JSON.stringify(env[key])
    return acc
  }, {})
  
  return {
    define: {
      'process.env': processEnv
    }
  }
})

安全警告

这种方法会将所有环境变量暴露给客户端，可能造成安全风险，请谨慎使用。

5. 使用系统环境变量

你可以在 .env 文件中引用系统环境变量：

# 直接引用系统变量
VITE_MY_VAR=${SYSTEM_VAR}

# 带默认值的引用
VITE_MY_VAR=${SYSTEM_VAR:-default_value}

6. 常见问题排查

如果环境变量仍然无法正常工作，请检查以下几点：

1. 文件位置：确保 .env 文件位于项目根目录，而不是 src 目录
2. 服务器重启：修改 .env 文件后需要重启开发服务器
3. 变量名匹配：检查代码中的变量名与 .env 文件中的名称是否一致
4. 模式匹配：Vite 支持不同模式的环境文件（如 .env.development, .env.production）

总结

Vite 的环境变量系统设计注重安全性，默认只暴露带有 VITE_ 前缀的变量。通过正确使用前缀、适当配置 Vite 以及在需要时使用 loadEnv() 函数，你可以灵活地在项目中使用环境变量。

最佳实践建议

• 始终使用 VITE_ 前缀标识需要暴露给客户端的环境变量
• 敏感信息应保持在服务器端，不要通过环境变量暴露给客户端
• 为不同环境创建不同的 .env 文件（如 .env.development, .env.production）
• 在团队协作项目中，提供 .env.example 文件说明所需的环境变量