python-dotenv 是一个 Python 库，用于从 .env 文件加载环境变量到应用运行环境中，是管理应用配置的黄金标准工具。

核心价值 #

1. 配置与代码分离 - 敏感信息不硬编码在源码中
2. 多环境支持 - 不同环境使用不同配置
3. 零配置协作 - 新成员克隆项目后立即拥有标准配置
4. 部署友好 - 无缝衔接各类部署平台的环境变量机制

基础使用 #

安装 #

pip install python-dotenv

典型工作流 #

1. 创建 .env 文件：

   # .env
   DEBUG=True
   DB_HOST=localhost
   API_KEY="your-api-key-here"

2. 在Python中加载：

   from dotenv import load_dotenv
   load_dotenv()  # 默认加载当前目录下的.env文件
   
   import os
   db_host = os.getenv("DB_HOST")

高级特性 #

1. 智能路径解析 #

load_dotenv("/custom/path/.env")  # 绝对路径
load_dotenv(".env.production")    # 不同环境配置

2. 优先级控制 #

load_dotenv(override=True)  # .env变量覆盖系统环境变量

3. 安全加载 #

from dotenv import dotenv_values
config = dotenv_values()  # 仅返回字典，不修改实际环境

4. 流式加载 #

from io import StringIO
from dotenv import dotenv_values

env_file = StringIO("""
SECRET=123
""")
config = dotenv_values(stream=env_file)

工程化实践 #

配置结构建议 #

project/
├── .env                # 本地开发默认配置
├── .env.test           # 测试环境配置
├── .env.production     # 生产环境配置模板
└── .gitignore          # 必须包含.env*

类型安全处理 #

from distutils.util import strtobool

DEBUG = strtobool(os.getenv("DEBUG", "false"))
PORT = int(os.getenv("PORT", "8000"))

框架集成示例 #

Flask集成:

from flask import Flask
app = Flask(__name__)
app.config.update(
    SECRET_KEY=os.getenv("FLASK_SECRET"),
    DATABASE_URI=os.getenv("DB_URI")
)

Django集成:

# settings.py
from dotenv import load_dotenv
load_dotenv()

SECRET_KEY = os.getenv("DJANGO_SECRET")

安全规范 #

1. 必须忽略 - 确保 .gitignore 包含：

   .env
   .env*.local

2. 模板维护 - 提供 .env.example：

   # .env.example
   DB_HOST=
   API_KEY=

3. 生产环境 - 应该：

   • 使用平台原生环境变量（如Heroku Config Vars）
   • 或通过CI/CD管道注入
   • 禁止直接上传.env文件

调试技巧 #

当变量未生效时检查：

from pprint import pprint
pprint(dict(os.environ))  # 查看所有环境变量

性能优化 #

对于高频调用场景：

# 项目启动时一次性加载
_env = dotenv_values()
SECRET = _env["SECRET"]  # 直接访问字典比os.getenv更快

典型应用场景 #

1. 数据库配置：

   # .env
   DB_ENGINE=postgresql
   DB_HOST=db.example.com
   DB_PORT=5432
   DB_USER=app_user
   DB_PASS=s3cr3t

2. 第三方API：

   import requests
   API_ENDPOINT = os.getenv("API_URL")
   response = requests.get(
       API_ENDPOINT,
       headers={"Authorization": os.getenv("API_TOKEN")}
   )

3. 特性开关：

   # .env
   FEATURE_NEW_UI=true

dotenv 通过简单的机制解决了配置管理的核心问题，是Python项目现代化开发的必备工具。正确使用可以使项目同时满足开发便捷性和生产安全性的要求。