Python返回None三种写法：字节码一致与mypy报错差

脚本专家

本文基于 CPython 3.11.9（macOS Apple Silicon）实测，类型检查用 mypy 2.3.1，覆盖率用 coverage 7.16.1。主题不是泛泛讨论 return None，而是拆解 Python 中三种返回 None 的写法为什么运行结果相同、字节码相同，却在行号、调试、覆盖率和 mypy 检查上表现不同。

一、三个函数与运行时结论
先看最常见的三种写法：

2. def foo1(value):
3.     if value:
4.         return value
5.     else:
6.         return None
8. def foo2(value):
9.     # 裸 return 等价于 return None
10.     if value:
11.         return value
12.     else:
13.         return
15. def foo3(value):
16.     # 函数末尾缺少 return
17.     if value:
18.         return value

复制代码

分别调用 foo1(0)、foo2(0)、foo3(0)，type 都是 <class 'NoneType'>。更硬的验证是 is 和 id：三者返回的都是同一个 None 单例，id 与 id(None) 完全相同，foo1(0) is foo2(0) is foo3(0) 也为 True。因此判空必须用 x is None，不要用 x == None，后者可能被自定义 __eq__ 干扰。

None 还有几个硬事实：type(None) 是 NoneType；Python 3.10 起可直接用 types.NoneType，type(None) is types.NoneType 为 True；None、True、False 从 Python 3 起是关键字，不能重新赋值或遮蔽，模块级和函数内执行 None = 1 都会抛 SyntaxError: cannot assign to None。所以 return None 中的 None 一定指向那个唯一单例，不存在被覆盖的可能。

二、字节码：三种写法编译产物逐字节一致
这是最反直觉的部分。用不带 docstring 的等价版本 n1、n2、n3 反汇编，指令序列完全相同：

2. RESUME
3. LOAD_FAST value
4. POP_JUMP_FORWARD_IF_FALSE (to 10)
5. LOAD_FAST value
6. RETURN_VALUE
7. LOAD_CONST None
8. RETURN_VALUE

复制代码

也就是说，显式 return None、裸 return、函数末尾什么都不写，CPython 都编译成同一段代码。编译器对隐式返回的处理就是自动补上 LOAD_CONST None 和 RETURN_VALUE。逐字节比较 co_code 也为 True：n1.__code__.co_code == n2.__code__.co_code，n1.__code__.co_code == n3.__code__.co_code。带 docstring 的一组内部也全为 True。跨组比较时为 False，原因不是语义差异，而是 docstring 占据 co_consts[0]：无 docstring 时 co_consts 是 (None,)，有 docstring 时是 ('doc', None)，反汇编里出现 LOAD_CONST 0 与 LOAD_CONST 1 的区别，但加载的都是同一个 None。

三、唯一可观测差异：隐式 return 的行号归属
指令相同，差异只能来自行号表。三者最后那条 LOAD_CONST None 的行号归属不同：return None 归属 return None 所在行；裸 return 归属 return 所在行；隐式返回归属函数体最后一行，也就是 if value: 那一行。用 sys.settrace 记录实际执行行号，n1(0) 是 [3, 6]，n2(0) 是 [10, 13]，n3(0) 只有 [17]。传 0 走“返回 None”路径时，n1、n2 有两行，n3 只有一行，返回动作不可见。

这一差异会影响调试器、trace/profiler 和覆盖率。用 coverage 7.16.1 对三者各调用一次 f(0) 时，语句覆盖率 Missing 为 6、13、20，都是三个函数里的 return value 真值分支。n3 的隐式 return 永远不会出现在 Missing 列表，因为它没有独立行号，覆盖率工具根本没有这一行可统计。换句话说，在 n3 写法下，一个函数是否真的走到了返回这一步，覆盖率工具无法观测。

四、mypy 把差异放大成不同错误码
加上返回类型标注后，同一个运行时行为在 mypy 2.3.1 下判定截然不同。实测错误如下：

2. ret_none_types.py:9: error: Incompatible return value type (got "None", expected "int") [return-value]
3. ret_none_types.py:16: error: Return value expected [return-value]
4. ret_none_types.py:19: error: Missing return statement [return]

复制代码

对应关系是：foo1 的 return None 报 Incompatible return value type，错误码 return-value，报在 return None 行；foo2 的裸 return 报 Return value expected，错误码 return-value，报在 return 行；foo3 的隐式返回报 Missing return statement，错误码 return，报在 def 那一行。三种写法三种描述，甚至两种错误码，报错位置也不同。

更尖锐的是，把标注放宽成 -> int | None 也救不了后两种：return None 可以通过，裸 return 仍然报 Return value expected，隐式返回仍然报 Missing return statement。也就是说，即使返回类型合法地包含 None，mypy 依然要求显式写出 return None 或在函数末尾给出显式 return。反过来，不加任何类型标注时，bar1/bar2/bar3 在默认模式与 --check-untyped-defs 模式下都没有报错，且两种模式输出相同。这套差异只在声明了返回类型时才会被检查器捕捉。

需要抑制时，三种报错都能精确封到单个错误码：return None 在 return 行写 # type: ignore[return-value]；裸 return 在 return 行写 # type: ignore[return-value]；隐式返回因为报在 def 行，所以必须在 def 行写 # type: ignore[return]。写在别处无效。

五、AST 层面的结构依据
差异在 AST 层就存在。n1 的 if orelse 分支中有 Return，Return.value 是 Constant(None)，即显式 None 常量。n2 的 Return.value 是 None，即缺值返回。n3 没有 orelse 分支，函数体末尾也没有 Return 节点。因果链因此很清楚：三种写法在 AST 层分岔，编译器把它们归一化成同样的字节码，而类型检查器保留了这个分歧。这就是“运行等价、静态不等价”的全部原因。

六、这三个函数真正做的事：假值归一化
抛开 None 的话题，这三个函数实际做的是：真值原样返回，假值一律转成 None。实测样本中，它们与 value or None 逐项一致，等价于：

2. lambda value: value or None

复制代码

会返回 None 的假值包括 0、0.0、0j、空字符串、空列表、空字典、空集合、空元组、None、False、b''。但有几个容易判断错的真值：float('nan') 是真值，foo1(nan) 返回 nan；字符串 '0' 和 'False' 是非空字符串，也是真值，会被原样返回；[0]、{'k': 0} 同样是非空容器，也是真值。从 JSON 或表单里读到的字符串 '0'、'False' 会绕过归一化。

七、真实 bug 模式与选型
典型误伤是这样的：

2. def get_count(n):
3.     # 本意：没有数据时返回 None
4.     if n:
5.         return n
6.     # 忘了写 else 分支，计数为 0 时静默返回 None

复制代码

实测 get_count(0) 返回 None，get_count(5) 返回 5。0 是合法计数，却被当成“没有数据”。这种隐式返回最难发现，因为函数看起来是对的，返回 None 也符合文档描述，只有调用方的 if x is None 分支会在生产环境里悄悄走错。

选型建议：有返回值但可能返回 None 时，优先显式 return None，mypy 在 -> T 下能精确报出值类型问题，意图无歧义。早退分支可以用裸 return。函数作为过程使用、本来就不该有返回值时，可以什么都不写，并且不要标注返回类型。如果业务需要区分“假值”与“无值”，不要用这套写法，应改成 return value if value is not None else None，或者直接保留 value 的 None 语义；判断也应写成 if value is not None:，而不是 if value:。

八、生成器中的 return 是另一回事
同样的三种写法放进生成器，运行结果仍然一致，但 return 有了新含义：return value 会变成 StopIteration.value。实测 g_bare 和 g_none 的 StopIteration.value 都是 None，仍然等价；g_value 中 return 42 会把 42 藏进 StopIteration.value，只有用 next() 手动捕获异常或 yield from 才能拿到，日常 for 循环会直接丢掉。需要传出值时应优先考虑 yield。

九、陷阱清单与速查

2. # 判空
3. x is None        # 正确
4. x == None        # 错误
6. # 需要区分假值与无值时
7. if x is not None:   # 正确：0、''、[] 会走进来
8. if x:               # 会把 0、0.0、''、[]、{}、()、None、False 一起过滤
10. # 类型检查忽略
11. return None  # type: ignore[return-value]
12. return       # type: ignore[return-value]
13. def f() -> T:  # type: ignore[return] 隐式返回的 ignore 写在 def 行

复制代码

其他易踩点包括：以为三种写法有运行时差异，实际 co_code 逐字节相同；以为隐式 return 没有开销，编译产物相同，真正代价在可维护性；float('nan') 被当作假值，实际 nan 是真值，数值场景应单独判 is None；字符串 '0'、'False' 被当作假值，实际原样返回，应先解析再判断；计数 0 被误判为无数据，判断应改为 is not None；隐式返回让调试器少一步，返回 None 时写显式 return None；覆盖率无法观测隐式返回；mypy 报错位置在 def 行；以为 -> int | None 能消除告警；无类型标注时检查器不介入。

十、小结
三种 return None 写法在运行时完全等价：返回同一个 None 单例，co_code 逐字节一致，性能上也没有差异。编译期 CPython 对没有返回值的路径一律补 LOAD_CONST None 和 RETURN_VALUE。唯一的客观裂缝是行号：隐式返回没有独立行号，导致 trace、调试器和覆盖率看不见这次返回。静态检查器把这个裂缝放大成不同错误码：return None 报 return-value，裸 return 报 return-value，隐式返回报 return 并以 def 行定位。运行等价不等于检查等价。真正该警惕的是业务语义：if value: 会把 0、''、[] 和 None 混为一谈，而 float('nan') 又是真值，会绕过归一化。选择写法时，优先让“故意返回 None”和“忘记写 return”在源码上可区分。