17370845950

推荐用 pydantic-settings 统一加载配置，自动按环境变量 > 配置文件 > 默认值优先级合并，支持类型校验与 ValidationError 提前报错，避免硬编码或手动读 YAML 导致的覆盖遗漏和上线故障。

用 os.environ + pydantic-settings 做配置入口最稳

硬编码环境判断或手动读 YAML 文件再拼路径，容易漏覆盖、难测试、上线出错。推荐用 pydantic-settings（pydantic v2+ 官方维护的子包）统一加载，它自动按优先级合并：环境变量 > 配置文件 > 默认值，且带类型校验和错误提示。

• settings.py 中定义一个继承 BaseSettings 的类，字段名即配置项名，类型注解即校验规则
• 通过 env_file 参数指定不同环境的 .env 文件，例如 .env.prod、.env.dev
• 环境切换靠 ENVIRONMENT 环境变量控制，不改代码、不重打包
• 启动时若字段缺失或类型不符，会直接抛 ValidationError，比运行中报 KeyError 更早暴露问题

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DATABASE_URL: str
    LOG_LEVEL: str = "INFO"
    DEBUG: bool = False

    class Config:
        env_file = f".env.{os.getenv('ENVIRONMENT', 'dev')}"
        case_sensitive = False

避免 .env 文件被 Git 提交的三个实操动作

本地开发用 .env.dev，但里面可能含数据库密码或密钥；CI/CD 里靠环境变量注入，不依赖文件。若没管好，轻则泄露凭证，重则触发安全扫描告警。

• 在 .gitignore 中明确加一行 .env.*，而不是只写 .env
• CI 脚本里用 export ENVIRONMENT=prod，再让 pydantic-settings 自动加载 .env.prod —— 但该文件本身不进仓库，由运维单独分发或注入
• 本地调试时，用 python -m pip install python-dotenv 并确保 pydantic-settings 的 env_file_encoding 设为 "utf-8"，否则中文注释或值会乱码

多环境配置继承与覆盖的真实写法

不是所有配置都要每环境写一遍。pydantic-settings 不支持 YAML 的 !include，但可以用 Python 层级继承模拟“基础配置 + 环境补丁”。

• 建 settings_base.py，定义公共字段如 APP_NAME、TIMEZONE
• 各环境 settings 类（如 DevSettings、ProdSettings）继承它，并只重写差异字段，比如 DEBUG = True 或 DATABASE_URL
• 最终实例化时用 Settings() 即可，无需手动选类 —— 因为 env_file 已由 ENVIRONMENT 决定
• 注意：字段默认值在基类里设，子类里不要重复设，否则会覆盖基类逻辑

os.getenv('ENVIRONMENT') 没生效？检查这三点

常见现象：本地跑是 dev，部署后还是读 .env.dev，日志里 DATABASE_URL 明明配了却没生效。

• 确认启动命令是否真正设置了环境变量，比如 ENVIRONMENT=prod python main.py，而不是 export ENVIRONMENT=prod && python main.py（后者在某些 shell 下不生效）
• 检查是否在 import settings 之前就调用了 os.getenv('ENVIRONMENT') —— pydantic-settings 初始化时才读，但你提前读可能拿到 None
• Docker 镜像里要显式传参：docker run -e ENVIRONMENT=prod myapp，不能只写 ENV ENVIRONMENT prod（构建时固定，无法运行时覆盖）

配置加载看似简单，但环境变量优先级、文件编码、Git 忽略粒度、Docker 启动参数这四点一旦错一个，就可能导致预发和线上行为不一致。建议把 Settings() 实例化放在应用入口最上方，加一行 print(f"Loaded env: {settings.ENVIRONMENT}") 快速验证。