Python python-dotenv vs pydantic-settings 的选型

dotenv加载失败主因是load_dotenv()未调用或时机过晚，需置于入口文件顶部；跨目录需显式指定路径；pydantic-settings提供类型校验与默认值但启动较慢，应延迟初始化。

dotenv 加载失败但没报错？检查 load_dotenv() 是否被忽略

很多项目里 .env 文件明明存在，os.getenv("DB_URL") 却返回 None——根本原因是 load_dotenv() 没被调用，或调用时机太晚（比如在模块导入后才执行）。python-dotenv 不自动加载，纯手动触发。

• load_dotenv() 必须在任何读取环境变量的代码之前调用，推荐放在入口文件（如 main.py 或 app.py）最顶部
• 如果用了子目录或包结构，注意 load_dotenv() 默认只找当前工作目录下的 .env，跨目录需显式传参：load_dotenv(".config/.env")
• 它不会覆盖已存在的环境变量（除非加 override=True），调试时可用 print(os.environ.get("KEY")) 确认是否真加载进去了

需要类型校验和默认值？别硬套 os.getenv() + int()

手写类型转换容易崩：比如 int(os.getenv("PORT", "8000")) 遇到空字符串或非数字就抛 ValueError；默认值逻辑也容易散落在各处。这时候 pydantic-settings 的优势就出来了——它把“读取→校验→转换→默认”全包了。

• 定义一个 Settings 类，字段带类型注解和 default 或 default_factory，pydantic-settings 自动从环境变量、.env 文件、甚至命令行参数按优先级合并
• 错误会集中抛出 ValidationError，提示明确（比如 “PORT field required” 或 “PORT must be a valid Integer”），而不是运行中随机崩在某一行
• 支持嵌套模型、SecretStr（自动掩码日志输出）、@field_validator 自定义逻辑，适合中大型服务配置

启动慢了一两百毫秒？留意 pydantic-settings 的初始化开销

pydantic-settings 启动时要解析模型、扫描所有环境源、做完整校验，比单纯 load_dotenv() + os.getenv() 多 5–10 倍耗时（实测约 50–200ms，取决于字段数和验证复杂度）。对 CLI 工具或短生命周期脚本影响明显。

• 如果只是简单读几个字符串，且不校验、无默认逻辑，python-dotenv 更轻量、更直接
• 可延迟初始化：不要在模块顶层创建 Settings() 实例，放到函数内或用 lru_cache 包一层，避免 import 时就执行
• 生产环境若用 gunicorn/Uvicorn，worker 进程多，这个开销会被放大，建议压测对比冷启动时间

部署到容器或 CI 时变量没生效？优先查 env_file 路径和加载顺序

本地跑得好，一上 docker 就 None，大概率是 .env 文件根本没被复制进去，或者 pydantic-settings 加载了系统环境变量却忽略了 .env ——因为默认不读 .env，得显式指定 env_file=".env"。

立即学习“Python免费学习笔记（深入）”；

• python-dotenv 的 load_dotenv() 默认只读当前目录 .env，Docker 中常因工作目录不对而失效；建议用绝对路径：load_dotenv("/app/.env")
• pydantic-settings 默认不加载任何 .env 文件，必须在 BaseSettings 子类里写 class Config: env_file = ".env"，或实例化时传 env_file=".env"
• 两者都遵循“环境变量 > .env 文件”优先级，CI/CD 中通过 export KEY=VAL 设置的变量会覆盖 .env 里的同名项，这点容易误判配置来源

真正难的不是选哪个库，而是想清楚：这个配置会不会变？要不要约束格式？有没有人会直接改环境变量绕过 .env？这些决定了你该用哪一层抽象——越靠近业务语义，越该用 pydantic-settings；越靠近基础设施胶水，python-dotenv 反而更稳。