python-dotenv：.env 配置管理，一行代码搞定

python-dotenv：.env 配置管理，一行代码搞定

python-dotenv 在 GitHub 上拿到了 8,778 Star。

这个 Python 库只做一件事：从 .env 文件读取键值对，注入到系统环境变量里。遵循 12-factor 应用原则，让本地开发和线上部署的配置管理保持统一。

1、这玩意儿是干嘛的

就一件事：把 .env 文件里的配置项变成环境变量。

写完代码要跑起来，数据库地址、API 密钥、调试开关这些配置怎么管？硬编码不安全，每次手动 export 又麻烦。python-dotenv 的做法很直接：项目根目录放一个 .env 文件，启动时一行 load_dotenv() 自动加载，后面的代码照常从 os.environ 取值，跟从系统环境变量来的一模一样。

from dotenv import load_dotenv

load_dotenv()  # .env 里的配置项自动写入 os.environ

.env 文件的语法跟 Bash 差不多，支持注释、变量引用、单双引号包裹的值，键值对之间用等号分隔。

2、为什么要用它

做过项目的都懂：配置散落在各个地方是件头疼的事。开发环境用 .env，测试环境用另一套，CI/CD 里又得单独设置。缺一个统一入口时，改个配置项要在几个地方同步，漏一处就是一小时的排查。

python-dotenv 把配置入口收敛到一个文件。.env 放项目根目录，加进 .gitignore，敏感信息不会提交到仓库。本地用 .env，线上用真正的环境变量，代码里对配置的访问方式完全一样。符合 12-factor 第三条"配置与代码分离"的原则。

3、几个实用的点

不覆盖已有环境变量。 默认 override=False，系统环境变量优先级高于 .env 文件。容器化部署时这一点很关键：K8s 注入的环境变量不会被本地开发配置意外覆盖。

支持变量展开。 .env 文件里可以写 ${DOMAIN} 引用其他变量，自动解析嵌套引用。写法跟 Bash 一致，没有额外的学习成本。

不碰环境也能取配置。 dotenv_values() 只返回一个 dict，不去改 os.environ。适合多份配置按优先级合并的场景：

from dotenv import dotenv_values

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

自带命令行工具。 装上 python-dotenv[cli]，终端里直接 dotenv set、dotenv list、dotenv run 操作 .env 文件，不需要手动打开编辑器。

4、适合哪些人用

• 写 Python 项目、需要管理本地开发环境变量的开发者
• 遵循 12-factor 原则、希望配置与代码分离的团队
• 在多环境之间切换、需要统一配置管理方案的人