Pitfall Journal

开发过程中踩过的坑，按时间倒序排列。 Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。

症状: 修改 .env 切换 API 供应商后，后端仍报旧供应商的错误（如 DeepSeek 报 "Model Not Exist"，实际发送的模型名是 OpenAI 的 gpt-4o-mini）
根因: 两层叠加：(1) load_dotenv() 默认 override=False，如果进程/系统中已有同名环境变量，.env 中的新值不会生效；(2) config.py 使用模块级常量 LLM_MODEL = os.getenv(...) 在 import 时就求值固化，而 main.py 的 import 链在 load_dotenv() 之前就触发了 config.py 的加载
解法: (1) load_dotenv(override=True) 并提到所有业务 import 之前；(2) config.py 改为函数式 get_llm_model()，运行时才读取
防御: 任何 Python 项目使用 dotenv 时，始终 override=True + 放在文件最顶部（仅在 import os 和 from dotenv import load_dotenv 之后）；配置值用函数或属性包装，不要用模块级常量
关联: Python, dotenv, FastAPI, uvicorn, 环境变量, 配置管理, OpenAI SDK