我本地 Python 版本是 3.14，服务器上 Python 版本是 3.12。
本地可以正常运行的代码放到服务器上执行失败了，排查后发现是类型注解中引用了后面才定义的类。

例如：

class Foo:
    def method(self) -> Bar:   # NameError: name 'Bar' is not defined
        ...

class Bar:
    pass

经过一番调研，发现是不同 Python 版本对 annotation 的求值策略不同（eager vs deferred），导致运行期是否触发 NameError 不一致。

Python 3.14 引入 PEP 649，使 annotation 采用延迟求值机制，从而允许这种写法；而在此之前的版本默认会在函数定义阶段立即求值，因此会报错，除非：

1. 调整定义顺序
2. 采用字符串类型注解

def method(self) -> "Bar":

1. 未来注解语义（Python 3.7+ 即可用）

from __future__ import annotations

参考资料

• What's New In Python 3.14 — PEP 649 & PEP 749
• annotationlib — 三种注解语义说明（stock / deferred / stringified）
• PEP 649 — Deferred Evaluation Of Annotations Using Descriptors
• PEP 563 — Postponed Evaluation of Annotations（from __future__ import annotations）