推荐用 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 明明配了却没生效。
立即学习“Python免费学习笔记（深入）”；
- 确认启动命令是否真正设置了环境变量，比如
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}") 快速验证。
