配置加载失败必须在import时立即报错，而非运行时；应将校验逻辑置于模块顶层或pydantic配置类初始化中，显式区分环境变量未设置（None）与为空字符串（""），并确保.env路径正确且存在。
配置加载失败时，import 就该报错，而不是等到运行时
Python 配置文件（如 config.py、.env）出错却沉默通过，是线上故障最常见源头之一。核心原则：**配置不是数据，是程序契约的一部分；契约失效，必须在模块导入阶段就中断**。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 避免在函数里懒加载配置，比如把
load_config()放在某个业务函数内部——它可能永远不被调用，错误就被掩盖 - 在配置模块顶层直接执行校验逻辑，例如：
import os if not os.getenv("DATABASE_URL"): raise ValueError("missing DATABASE_URL in environment") - 用
pydantic.BaseSettings（v1）或pydantic-settings（v2）定义配置类，构造实例时自动校验类型和必填项，比手写if not xxx更可靠
os.getenv() 返回 None 还是空字符串？别靠猜
环境变量未设置时，os.getenv("KEY") 返回 None；但若设成了空值（如 KEY=），它返回空字符串 ""。这两者语义完全不同，但很多代码用 if not os.getenv("KEY"): 一把抓，结果把合法的空配置也判为缺失。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 显式区分：用
os.getenv("KEY") is None判断是否未设置；用not os.getenv("KEY", "")判断是否为空（含""和None） - 对敏感配置（如密钥、URL），宁可多一次检查：如果业务上不允许空字符串，就加
if os.getenv("SECRET") == "": raise ValueError("SECRET cannot be empty") - 注意 Docker 或 systemd 环境下，
ENV KEY=会生成空字符串，而非未设置，这点和本地 shell 直接unset KEY不同
用 pydantic-settings 做配置时，_env_file 路径没生效？
pydantic-settings 默认只读当前目录下的 .env，不会向上递归查找，也不会自动识别项目根目录。很多人把 .env 放在项目根目录，却在子包里 import config，导致加载失败且无提示。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 显式传入绝对路径：
from pydantic_settings import BaseSettings class Settings(BaseSettings): DB_URL: str class Config: _env_file = Path(__file__).parent.parent / ".env" - 或者更稳妥：用
find_dotenv()（来自python-dotenv），它按标准规则从当前工作目录向上找.env，再传给BaseSettings的_env_file - 切记：如果
_env_file指向的文件不存在，pydantic-settings默认静默忽略——必须手动加_env_file_encoding = "utf-8"并配合异常捕获，或改用dotenv.load_dotenv()提前加载并检查返回值
测试环境里配置没报错，上线就崩？检查 __name__ == "__main__" 的陷阱
有些配置模块为了调试方便，在顶层写了类似 if __name__ == "__main__": load_and_print_config() 的代码。本地跑脚本没问题，但一旦被其他模块 import，这段逻辑就会执行——而此时环境可能不完整（比如缺少 CI/CD 注入的 secret），导致导入失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 所有副作用操作（读文件、连数据库、发 HTTP 请求）必须封装进函数，禁止在模块顶层裸写可执行逻辑
- 配置模块应保持“纯声明”：只定义类、常量、默认值；校验逻辑放在类的
__init__或@validator中，由实例化触发 - CI 流水线里跑单元测试时，确保测试启动路径与生产一致（比如都从项目根目录
python -m pytest），否则__file__和工作目录偏差会导致路径相关配置失效
import 时就炸出来——而不是等请求打进来、日志刷屏、监控告警才看到 KeyError: 'REDIS_URL'。越早暴露，修复成本越低，这个时间点卡在模块导入阶段，不是函数调用时。 
