python-dotenv：从 .env 文件加载环境变量

python-dotenv：从 .env 文件加载环境变量

python-dotenv 是一个用于读取 .env 文件并将键值对设置为环境变量的 Python 库，目前获得了 8,779 个 Star。

该库的设计目标是为遵循 12-factor 原则的应用提供配置管理方案。开发阶段通常需要手动设置环境变量，这种方式在频繁切换项目时不够方便。python-dotenv 允许在项目根目录放置 .env 文件，在应用启动时自动加载其中的配置，同时保留通过真实环境变量覆盖的能力。

安装方式如下：

pip install python-dotenv

基础用法只需两行代码：

from dotenv import load_dotenv

load_dotenv()

调用 load_dotenv() 后，.env 文件中的变量会被读取到 os.environ 中，后续代码可以像访问普通环境变量一样使用它们。

默认行为遵循安全原则：不会覆盖已存在的环境变量。如需强制覆盖，可以传入 override=True。

.env 文件的语法接近 Bash，支持注释和变量引用：

# 开发环境配置
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app

需要注意的是，变量引用需要使用 ${VAR} 的形式，裸变量 $VAR 不会被解析。

除了直接修改环境变量，python-dotenv 还提供了 dotenv_values 函数。它与 load_dotenv 工作方式相近，但只返回解析后的字典，不改变当前环境：

from dotenv import dotenv_values

config = dotenv_values(".env")

这个特性适合需要灵活合并多份配置的场景。例如，可以将共享配置和敏感配置分开存放，再按优先级合并：

import os
from dotenv import dotenv_values

config = {
    **dotenv_values(".env.shared"),
    **dotenv_values(".env.secret"),
    **os.environ,
}

python-dotenv 支持流式输入，可以从内存或网络等非文件源加载变量：

from io import StringIO
from dotenv import load_dotenv

config = StringIO("USER=foo\nEMAIL=foo@example.org")
load_dotenv(stream=config)

对于 IPython 用户，该库提供了魔术命令扩展：

%load_ext dotenv
%dotenv

命令行工具也包含在内。安装 CLI 依赖后，可以直接在终端查看和修改 .env 文件：

pip install "python-dotenv[cli]"
dotenv set USER foo
dotenv list
dotenv run -- python app.py

文件格式方面，python-dotenv 支持单行和多行值、单双引号、注释行以及 export 前缀。变量插值遵循 POSIX 规范，未定义变量会依次回退到环境变量值、默认值或空字符串。

如果需要临时禁用自动加载，可以设置环境变量 PYTHON_DOTENV_DISABLED=1，load_dotenv() 将不再读取任何文件或流。

这个库解决的问题很具体：让本地开发和生产部署在环境变量层面保持一致，同时给开发者一个不必手动导出变量的工作流。它的代码量不大，但在 Python 项目的配置管理中被广泛使用。