直接访问 os.environ["KEY"] 抛出 KeyError 是因环境变量缺失而非代码错误，常见于不同部署环境变量名不一致或未设置；应优先用 os.environ.get("KEY", default) 避免异常，关键变量用 require_env 强校验，排查时需确认变量名拼写、大小写及注入时机。
为什么 os.environ["KEY"] 会抛出 KeyError
直接访问 os.environ["KEY"] 时，Python 不会做兜底处理——只要系统或当前进程里没设这个环境变量，就立刻崩，报 KeyError: 'KEY'。这不是代码写错了，而是运行时依赖缺失。常见于本地开发能跑、CI/CD 或 Docker 容器里挂掉，或者不同部署环境变量名不一致（比如本地用 DB_URL，线上用 DATABASE_URL）。
用 os.environ.get() 替代方括号取值
这是最轻量、最常用的解法：用 .get() 方法带默认值，避免异常中断。
-
os.environ.get("API_TOKEN")→ 返回None（安全，但后续可能引发TypeError） -
os.environ.get("API_TOKEN", "default-secret")→ 明确 fallback 值，适合测试或降级场景 -
os.environ.get("LOG_LEVEL", "INFO").upper()→ 可链式调用，但注意默认值类型要匹配后续操作
⚠️ 注意：.get() 返回的是字符串，哪怕你期望的是数字或布尔值，得自己转——比如 int(os.environ.get("PORT", "8000"))。
需要强校验时，用 os.getenv() + 显式报错
有些变量绝不能缺（如数据库密码），这时不能静默 fallback，而要立刻暴露问题。推荐封装一个简单函数：
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
立即学习“Python免费学习笔记（深入）”；
def require_env(key: str) -> str:
value = os.getenv(key)
if value is None:
raise ValueError(f"Missing required environment variable: {key}")
return value
<h1>使用</h1><p>db_password = require_env("DB_PASSWORD")比反复写 if not os.environ.get(...) 更干净，也比裸 os.environ["DB_PASSWORD"] 更易定位错误源头。
Docker 或 CI 中漏设变量的排查技巧
不是所有环境变量都来自 shell 启动时；Docker 的 ENV 指令、.env 文件、GitHub Actions 的 secrets 都可能没生效。
- 在入口脚本开头加
print(list(os.environ.keys()))，确认变量名拼写和大小写（Linux 区分大小写） - Docker 里用
docker run --env KEY=VALUE或-e KEY（后者需宿主机已有该变量） - 用
python -c "import os; print(os.environ.get('MISSING_KEY'))"单行验证，排除应用代码干扰 - Pydantic Settings 或
python-decouple这类库能统一管理，但引入新依赖前先确认是否真有必要
环境变量缺失本质是部署契约断裂，修复重点不在代码怎么 catch，而在明确谁该提供、何时提供、如何验证。变量名 typo 和作用域隔离（比如 systemd service 默认不继承用户环境）才是高频根因。
