前端环境变量 .env 怎么管理？VITE_ 前缀和 NODE_ENV 有什么坑？

Question

仓乃文 · Accepted Answer

环境变量管理不好会导致：API 地址写死在代码里、密钥泄露到前端、多环境切换混乱。

Vite 环境变量规则：
```bash
# .env 文件加载顺序（后者覆盖前者）
.env → .env.local → .env.development → .env.development.local
.env → .env.local → .env.production → .env.production.local

# 关键规则：只有 VITE_ 前缀的变量才会暴露给客户端！
VITE_API_URL=https://api.example.com    # 代码中可访问
SECRET_KEY=abc123                        # 代码中访问不到！安全！

# 代码中使用
const apiUrl = import.meta.env.VITE_API_URL;  // 正确
const secret = import.meta.env.SECRET_KEY;     // undefined！
```

NODE_ENV 的坑：
```bash
# 坑 1：不要手动覆盖 NODE_ENV
# Vite 的 NODE_ENV 由命令决定：
# vite dev → NODE_ENV=development
# vite build → NODE_ENV=production

# 坑 2：用 NODE_ENV 判断环境不够精确
# 应该用自定义变量区分
VITE_ENV=staging  # 更精确的环境标识
```

多环境配置方案：
```bash
# .env.staging
VITE_API_URL=https://staging-api.example.com
VITE_ENV=staging

# package.json
{
  "scripts": {
    "build:staging": "vite build --mode staging",
    "build:prod": "vite build --mode production"
  }
}
```

安全注意事项：
```bash
# 敏感信息绝对不能有 VITE_ 前缀
# 错误：VITE_DB_PASSWORD=abc123  会暴露到前端！
# 正确：DB_PASSWORD=abc123       代码中访问不到

# .env.local 加入 .gitignore
echo ".env.local" >> .gitignore
```

补充说明：
- 规则：只有 VITE_ 前缀的变量才暴露给前端，敏感信息不要加 VITE_
- 不要手动覆盖 NODE_ENV
- 用 --mode 区分环境，比只用 NODE_ENV 更灵活
- .env.local 存个人配置，不提交到 Git
- CI 中的密钥通过 secrets 注入