极客工场

Appearance

共 2,183 字预计阅读约 7 分钟

Python assert 被优化掉速查：python -O 删除断言导致校验失效六因 ​

更新时间：2026-10-24。FAQ 速查页，面向「本地测试一切正常、上了生产校验全消失」的同学。Python assert 失效不是报错型故障，而是沉默型故障：python -O（优化模式）启动时解释器把全文所有 assert 语句当空气删掉，于是你写的参数校验、权限检查、状态不变量一夜之间全部不执行——不抛任何异常，程序只是「不再检查」。最阴的部分在于它常常不是你自己加的 -O，而是部署模板、容器镜像、PYTHONOPTIMIZE 环境变量悄悄带上的。本篇把六类失效形态、__debug__ 的真实语义、断言与显式 raise 的分工一次讲清，核心原则只有一条：assert 只写给开发者看的调试检查，任何影响正确性与安全性的校验必须显式 raise。

本文要回答的问题 ​

  • 为什么加了 -O 之后 assert 一行都不执行了？
  • assert check_and_write() 这种写法为什么被称为灾难？
  • 单元测试全绿，为什么生产上还能漏掉断言要拦的坏数据？
  • __debug__ 和 -O 到底什么关系，能拿它写分支吗？
  • 哪些检查该用 assert、哪些必须显式 raise？

一、报错原文与典型现象 ​

这类故障没有报错——没有报错正是它的报错。典型的「发现瞬间」长这样（工程路径以 /proj/demo 占位）：

bash
$ python3 /proj/demo/check_demo.py
AssertionError: amount must be positive
# 本地开发：断言正常拦截负数

$ python3 -O /proj/demo/check_demo.py
$ # 什么都没发生——同一份代码，断言凭空消失
bash
$ PYTHONOPTIMIZE=2 python3 /proj/demo/app.py
# 生产启动脚本里藏着这个环境变量；
# 全文 assert 与文档字符串一起被剥掉，无任何提示

认清机制一句话：-O 让编译器在生成字节码时直接把 assert 语句从语法树上摘掉，等价于这些行从未存在；同时内建常量 __debug__ 从 True 变 False（-OO 还会额外剥 docstring）。这不是「跳过执行」，是「代码不存在」。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
生产不拦坏数据、本地拦启动命令带 -O / -OOpython3 -c "import sys; print(sys.flags.optimize)"关键校验改显式 raise
容器里断言全失效镜像 ENV 设了 PYTHONOPTIMIZE=1容器内 echo $PYTHONOPTIMIZE去掉变量或代码改 raise
写库动作在 -O 下不执行副作用调用写进 assert 表达式全局搜 assert .*\( 审一遍副作用移出断言单独成句
测试绿但线上断言漏拦测试不加 -O、生产加 -O对比两边 sys.flags.optimizeCI 加一条 -O 模式跑测试
if __debug__: 分支不执行同上，-O 下 __debug__ 为 False打印 __debug__ 值只放调试代码，勿放业务逻辑
安全校验形同虚设权限/边界检查用了 assert安全相关代码逐条审一律 if not ok: raise 改写

三、排查决策图 ​

这张图是断言失效排查的标准动线：红是失效现象与定罪根因，蓝是排查动作，绿是验证通过，橙是修复动作，紫是防复发沉淀。

languages/python/ts-python-assert-optimized-away.md D2 示意图

读这张图抓住主线：这类故障的定位不是「找报错」，而是先确认当前进程是不是优化模式——一条 sys.flags.optimize 就能定生死；然后把全文 assert 分两类：纯调试断言留着无妨，业务校验全部改写成显式 raise，这是唯一治本动作。

四、逐条排查展开 ​

第一病因：启动命令带 -O 而校验写在 assert 里。 最普遍形态。部署脚本为了「省一点内存、快一点启动」加了 -O，于是 assert user.is_admin 这种权限检查、assert amount > 0 这种边界检查全部蒸发。验证：生产进程里跑 python3 -c "import sys; print(sys.flags.optimize)"，输出 1 或 2 即定罪。处置：所有影响正确性与安全性的检查改成显式异常：

python
if amount <= 0:
    raise ValueError("amount must be positive")

assert 只保留给「绝不可能发生、发生了说明代码本身有 bug」的内部不变量。

第二病因：PYTHONOPTIMIZE 环境变量悄悄开启。 比你想象的常见：某些基础镜像（尤其是标榜 slim/production 的）、某些 supervisor/systemd 模板默认带 ENV PYTHONOPTIMIZE=1。你本地 docker run 没感觉，因为测试从不进容器跑。验证：容器里 echo $PYTHONOPTIMIZE 或看 Dockerfile。处置：镜像里去掉该变量，或接受它并把所有业务校验改 raise——后者更稳，因为你控制不了下游谁再开一次。

第三病因：副作用写进 assert 表达式。 灾难级写法：assert queue.push(item)、assert cache.invalidate(key)——正常模式下表达式求值、副作用执行；-O 下整句删除，副作用跟着没了，数据静默丢失。验证：全局搜 assert 后跟函数调用的写法，逐条人工审。处置：副作用永远独立成句，断言只检查其结果：

python
ok = queue.push(item)
assert ok  # 仅调试期自检，生产无所谓

第四病因：测试与生产语义分叉。 CI 跑 pytest 用的是普通模式，断言全开、全绿；生产跑 -O，断言全关、裸奔。于是「测试覆盖了校验逻辑」成为幻觉——你测的那层校验在生产根本不存在。处置：CI 流水线加一条 PYTHONOPTIMIZE=1 pytest 双模式跑测，凡是在优化模式下行为分叉的用例立即现形；分叉用例对应的检查一律改 raise。

第五病因：滥用 if __debug__: 放业务逻辑。 -O 下 __debug__ 编译期被替换为 False，该分支字节码直接不生成——和 assert 同机制。把计费、日志落盘、状态迁移写进 if __debug__: 块的人，等于亲手埋了一颗只在生产爆炸的雷。处置：__debug__ 分支只放「贵的调试检查」（如深拷贝后比对前后状态），业务逻辑一行都不许进。

第六病因：团队规范缺失——assert 语义没对齐。 一半人拿 assert 当「输入校验」，一半人拿它当「调试辅助」，代码库里两种语义混杂，谁也说不清哪条会在 -O 下消失。处置：团队立一条硬规矩——对外（用户输入、网络数据、文件内容）的检查永远 raise；assert 只对内部不变量，且被删掉不影响任何外部行为。配 linter 规则（如 flake8-bandit 的 S101 在生产代码告警 assert 使用）机器化执行。

五、规范做法与预防 ​

  • 分工写死：assert = 开发者调试断言（删了无影响）；显式 raise = 业务与安全校验（必须在场）。评审时见到 assert 拦外部输入直接打回。
  • CI 双模式跑测：普通模式 + PYTHONOPTIMIZE=1 各跑一遍，行为分叉即失败，把「测试绿生产炸」拦在合并前。
  • 部署清单显式化：启动命令与镜像 ENV 里是否带 -O/PYTHONOPTIMIZE 写进部署文档，不许「默认模板带的」这种糊涂账。
  • linter 兜底：生产代码目录开 bandit S101 类规则，assert 出现即告警，由人确认它真是调试断言。
  • 副作用洁癖：任何「会做动作」的调用不许出现在 assert 表达式里，code review 与 linter 双层把关。

这一篇在知识体系里的位置 ​

本篇是 Python 排错速查簇的语义陷阱篇，与「行为分叉」类问题互补：测试偶发失败看 Python 测试偶发失败速查；版本行为差异看 Python 版本不匹配速查；缓存导致「改了不生效」看 pycache 与 pip 缓存陈旧速查；语法层报错看 Python 语法错误速查；同批姊妹篇看 Python 磁盘写满速查 与 datetime 时区坑速查。「外部检查 raise、内部不变量 assert」这条分界线对任何语言的断言机制通用。

一句话总结 ​

assert 失效的本质是 -O/PYTHONOPTIMIZE 在编译期把断言从字节码里删除、并把 __debug__ 置 False，不报错、不提示，只是检查不存在了；六因处置——启动参数与环境变量先查 optimize 标志、业务与安全校验全部改显式 raise、副作用调用移出断言表达式、CI 加优化模式双跑、__debug__ 分支只放调试代码、团队立规矩配 linter 卡死 assert 拦外部输入；定位一件套是 sys.flags.optimize，防复发主线是「断言只验内部不变量」的编码规范加双模式测试，让校验在开发与生产语义一致。