您的应用程序需要一个数据库 URL。在你的笔记本电脑上，它是一个本地数据库，在 CI 中是一个一次性数据库，在生产中是一个托管集群。对其中任何一个进行硬编码都意味着更改每个环境的代码。 环境变量解决了这个问题。代码读取DATABASE_URL，每个环境提供自己的值。

这个想法是十二因素应用程序方法的核心，该方法表示部署之间不同的配置属于环境。我们在 Windows 上使用 Python 3.13 测试了以下行为。显示的每个输出都来自该运行。

什么是环境变量？

每个正在运行的进程都有一组命名文本值，称为其环境。熟悉的示例有 PATH，它告诉 shell 在哪里查找程序，以及 HOME 或 USERPROFILE。您自己的应用程序可以使用相同的机制进行 APP_PORT、LOG_LEVEL 或 DATABASE_URL 等设置。

设置环境变量

这些仅持续当前终端会话。要使它们永久存在，请将它们添加到 shell 配置文件中，例如 ~/.bashrc，或者在 Windows 上使用系统环境设置或 setx。对于应用程序，通常最好在部署时提供它们，而不是在系统范围内设置它们。

在代码中读取它们

import os

port = os.environ.get("APP_PORT", "8000")   # default if missing
print(port)                                  # 8000

db = os.environ["DATABASE_URL_MISSING_DEMO"]
# KeyError: 'DATABASE_URL_MISSING_DEMO'

使用 .get() 作为可选设置的默认值。使用方括号（它会引发 KeyError）来表示应用程序在没有方括号的情况下无法工作的设置。其他语言类似：Node.js 中的 process.env.APP_PORT、Java 中的 System.getenv("APP_PORT") 和 Go 中的 os.Getenv("APP_PORT")。

一切都是字符串

这吸引了各种语言的人们。我们设置一个端口，然后添加“1”：

os.environ["APP_PORT"] = "8080"
port = os.environ["APP_PORT"]
print(type(port).__name__, repr(port), port + "1")
# str '8080' 80801

os.environ["APP_PORT"] = 8080
# TypeError: str expected, not int

该值以文本形式返回，并添加生成的 80801，而不是 8081。显式转换，如 int(os.environ["APP_PORT"]) 中所示。布尔值更糟糕：

os.environ["DEBUG"] = "false"
print(bool(os.environ["DEBUG"]))   # True

在 Python 中任何非空字符串都是真值，因此 "false" 变成了 True。调试模式将在生产中打开。故意解析布尔值：

def env_bool(name, default=False):
    value = os.environ.get(name)
    if value is None:
        return default
    return value.strip().lower() in {"1", "true", "yes", "on"}

env_bool("DEBUG")                   # False
env_bool("NOT_SET", default=True)   # True

进程如何继承它们

子进程接收其父进程环境的副本。我们启动子 Python 进程来查看这一点：

child sees: 8080 inherited     # default: full copy of the parent's environment
child sees: 9000 None          # given a custom env: only what we passed
parent sees child var: None    # a child's changes never flow back

接下来是三个实践课程。您导出的变量对于您启动的每个程序都是可见的，包括您没有编写的脚本，这对机密很重要。通过自定义环境会替换整个事情，因此请包含孩子需要的任何内容。并且脚本无法更改其父 shell 的变量，这就是工具要求您 source 文件而不是运行它的原因。

.env 文件

手动输入许多变量会很乏味，因此大多数项目将本地开发值保存在 .env 文件中：

# local development only
APP_PORT=8080
DATABASE_URL="postgres://dev:devonly@localhost:5432/shop"
FEATURE_SEARCH=true

python-dotenv 和 Node.js 的 dotenv 等库会在启动时加载此文件。 Node.js 20.6 及更高版本也可以使用 --env-file 本地加载。为了了解这个想法，我们编写了一个小型解析器，它将上面的文件转换为：

{'APP_PORT': '8080',
 'DATABASE_URL': 'postgres://dev:devonly@localhost:5432/shop',
 'FEATURE_SEARCH': 'true'}

在实践中使用真实的库。它处理我们的 10 行版本忽略的引用、转义、注释和多行值。默认情况下，大多数 dotenv 加载器不会覆盖已设置的变量，因此真实的环境值胜过文件。这通常就是您想要的。

启动时验证配置

丢失的变量应该立即停止应用程序并发出明确的消息，而不是在一小时后导致令人困惑的错误。我们在加载时检查了所需的设置：

REQUIRED = ["DATABASE_URL", "SECRET_KEY"]

def check_required(env):
    missing = [k for k in REQUIRED if not env.get(k)]
    if missing:
        raise SystemExit(f"Missing required settings: {', '.join(missing)}")

# Missing required settings: SECRET_KEY

类型化配置库更进一步。 Python 中的 Pydantic 设置、Node.js 中的 zod 或 envalid 以及 Java 中的 Spring 配置属性都会立即转换类型并报告每个问题。

环境变量和秘密

环境变量是将 API 密钥等秘密传递给应用程序的常用方法，它们比硬编码要好得多。他们确实有弱点需要了解：

• 正如我们的测试所示，子进程继承它们。
• 它们可能出现在崩溃报告、调试页面和转储环境的日志中。
• 在某些系统上，同一用户运行的其他进程可以读取它们。

对于生产，许多团队将机密保存在专用管理器中，例如 HashiCorp Vault、AWS Secrets Manager、Azure Key Vault 或 Google Secret Manager，并在运行时注入它们。有些人更喜欢将机密安装为文件而不是变量。无论哪种方式，都不要在日志中打印配置，并轮换曾经提交给 Git 的任何秘密，即使在您将其从历史记录中删除之后也是如此。

在 Docker 和 CI 中

# Docker (not run for this article)
docker run -e APP_PORT=8080 --env-file .env.production myapp

# GitHub Actions (not run for this article)
env:
  APP_PORT: 8080
  API_KEY: ${{ secrets.API_KEY }}

CI 平台以加密方式存储机密，并在日志中隐藏它们。避免在 Dockerfile 中使用 ENV 将机密烘焙到 Docker 镜像中，因为它们在镜像层中仍然可读。有关完整设置，请参阅 我们的 Docker Compose 教程 和 GitHub Actions CI/CD 指南。

最佳实践

• 使用带有前缀的清晰大写名称，例如 SHOP_DB_URL。
• 读取一个模块中的所有配置，转换类型，并在启动时验证。
• 仅为非敏感设置提供安全默认值。
• 将 .env 排除在 Git 之外并维护 .env.example。
• 在生产中使用机密管理器来获取敏感值。
• 记录每个变量、其类型和示例值。

调试环境变量问题

当应用程序表现得好像缺少设置时，请按顺序完成这些检查：

1. 它设置在正确的位置吗？ 在一个终端选项卡中导出的变量在另一个终端选项卡中或在系统启动的服务中不存在。
2. 应用程序是否已重新启动？ 正在运行的进程会保留其启动时的环境。之后更改变量在重新启动之前不会产生任何影响。
3. 名称准确吗？ Linux 和 macOS 上的名称区分大小写，因此 App_Port 和 APP_PORT 是不同的变量。 Windows 将它们视为相同的。
4. .env 文件是否覆盖它，或者被忽略？ 检查您的加载程序是否覆盖现有值，以及它实际读取哪个文件。
5. 是否存在杂散引号或空格？ 使用尾随空格或额外引号复制的值可能无法解析或无法匹配，其方式很难发现。

要查看进程真正收到的内容，请打印变量名称，而不是秘密值。在 Linux 和 macOS 上，printenv 列出当前 shell 的环境，在 PowerShell 中 Get-ChildItem Env: 执行相同的操作。在容器内，运行 env 到 docker exec 显示容器的视图，该视图通常与您自己的 shell 的视图不同。

最后一点提示：在启动时记录一行，列出哪些可选设置正在使用其默认值。它不需要花费任何成本，而且它可以回答最多的问题“为什么要这样做？”立即提问。

最后的话

环境变量很简单，但它们隐藏了一些陷阱：一切都是字符串，孩子们继承它们，并且秘密可以通过它们泄漏。将它们视为应用程序的输入。在一个地方读取它们，尽早转换和验证它们，并在提交的文件中保留真正的秘密。

常见问题

继续学习