Skip to main content

现代应用环境变量完全指南

关于管理环境变量您需要了解的一切——从本地开发到生产环境部署。包含最佳实践以及需要避免的常见错误。

管家婆团队 2025年12月01日 2 分钟阅读
部署 教程

环境变量是每个开发者都在用、但很少有人真正精通的事物之一。使用得当时，它们能让您的应用既灵活又安全；使用不当时，它们则会成为缺陷和安全漏洞的来源。

本指南涵盖了您在现代 Web 开发中需要了解的关于环境变量的一切。

什么是环境变量？

环境变量是存在于应用程序代码之外的键值对。它们使您能够：

  • 在不更改代码的情况下配置行为
  • 让密钥远离版本控制
  • 为不同环境使用不同的设置

一个简单的示例：

DATABASE_URL=postgres://localhost:5432/myapp
API_KEY=sk_live_abc123
DEBUG=true

环境变量为何重要

安全性

在代码中硬编码密钥是非常危险的：

// ❌ 绝不要这样做
const apiKey = "sk_live_abc123";

// ✅ 应该这样做
const apiKey = process.env.API_KEY;

如果密钥写在代码中，它们最终会出现在：

  • 版本控制历史记录中（永久留存）
  • 构建产物中
  • 错误日志和堆栈跟踪中

环境变量让密钥与代码保持分离。

灵活性

同一套代码库应当能够在多个环境中运行：

  • 开发环境：本地数据库、调试日志
  • 预发布环境：测试数据库、类生产环境设置
  • 生产环境：真实数据库、经过优化的设置

环境变量使这一切无需更改代码即可实现。

十二要素应用方法论

十二要素应用方法论建议将配置存储在环境变量中。这种方法如今已成为行业标准，这是有充分理由的。

最佳实践

1. 本地开发使用 .env 文件

在项目根目录创建一个 .env 文件：

# .env
DATABASE_URL=postgres://localhost:5432/myapp_dev
API_KEY=sk_test_development
DEBUG=true

使用 dotenv 之类的库加载它：

import 'dotenv/config';
console.log(process.env.DATABASE_URL);

重要提示：务必将 .env 添加到您的 .gitignore 中！

2. 提供模板文件

创建一个 .env.example 文件，记录所需的变量：

# .env.example
# 将此文件复制为 .env 并填入相应的值

# 数据库连接字符串
DATABASE_URL=

# 外部服务的 API 密钥
API_KEY=

# 是否启用调试模式（true/false）
DEBUG=false

这能帮助新的团队成员快速上手。

3. 尽早校验

不要等到运行时才发现变量缺失：

const required = ['DATABASE_URL', 'API_KEY'];

for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}

更好的做法是使用 envalid 或 zod 之类的校验库。

4. 使用具有描述性的名称

良好的命名能让配置不言自明：

# ❌ 含义不清
URL=https://api.example.com
KEY=abc123

# ✅ 清晰明确
PAYMENT_API_URL=https://api.stripe.com
STRIPE_SECRET_KEY=sk_live_abc123

5. 为框架专属变量添加前缀

许多框架都有自己的约定：

  • Next.js：客户端变量使用 NEXT_PUBLIC_ 前缀
  • Vite：客户端变量使用 VITE_ 前缀
  • Create React App：客户端变量使用 REACT_APP_ 前缀

请遵循这些约定以避免混淆。

常见错误

错误 1：提交密钥

即使您从代码中删除了密钥，它仍然保留在 git 历史记录中。如果不慎提交了密钥：

  1. 立即轮换该密钥
  2. 使用 git-filter-repo 之类的工具将其从历史记录中移除
  3. 将该密钥视为已泄露

错误 2：在本地使用生产环境密钥

绝不要在开发环境中使用生产环境凭据。请为每个环境创建独立的凭据。

错误 3：将服务端变量暴露给客户端

在前端框架中，只有带有特定前缀的变量才会暴露给浏览器。不要绕过这一机制——它的存在是为了安全。

错误 4：不设置默认值

对于非敏感配置，应提供合理的默认值：

const port = process.env.PORT || 3000;
const logLevel = process.env.LOG_LEVEL || 'info';

Virex 中的环境变量

Virex 让环境变量管理变得简单：

设置变量

通过仪表盘或 CLI 添加变量：

virex env set DATABASE_URL="postgres://..."
virex env set API_KEY="sk_live_..." --secret

--secret 标志会对值进行加密，并在日志中将其隐藏。

按环境设置不同的值

为不同环境设置不同的值：

virex env set API_URL="https://api.example.com" --production
virex env set API_URL="https://staging-api.example.com" --preview

预览部署

预览部署会自动继承预览环境的配置，因此您可以使用合适的（非生产环境）凭据进行测试。

总结

环境变量是构建安全、灵活的应用程序的基础工具。核心原则如下：

  1. 绝不将密钥提交到版本控制
  2. 不同环境使用不同的值
  3. 在启动时校验配置
  4. 记录所需的变量

对 Virex 中的环境变量有疑问？请查阅我们的文档或联系技术支持。