Python 3.14 自由线程文档完善后，扩展兼容性怎么评估

Python 3.14 的关键变化，不是“从此默认关闭 GIL”，而是自由线程构建进入了官方支持阶段：它不再被视为实验功能，但依旧需要选择专用构建，并且运行时仍可重新启用 GIL。对应用团队来说，真正的问题也从“能不能尝鲜”变成了“整条依赖链是否真的在无 GIL 状态下工作”。

官方资料：https://docs.python.org/3/howto/free-threading-python.html
https://docs.python.org/3/howto/free-threading-extensions.html

评估时不要把“安装成功、导入成功”当成结论。一个未声明自由线程支持的原生扩展被导入时，解释器会给出警告并重新启用 GIL；程序看起来照常运行，实际却已经退出自由线程模式。

变化一句话：受支持，但仍然是可选模式

PEP 779 将 Python 3.14 定义为自由线程支持的第二阶段：功能进入正式支持范围，兼容 API 和文档更加稳定，生态可以据此安排生产迁移；但是否进入默认构建仍未决定。换句话说，3.14 给出的不是“一键提速”承诺，而是一条可以开始认真验收的技术基线。

评估时首先分清两个问题：当前解释器是不是自由线程构建，以及当前进程里的 GIL 是否仍然开启。前者是构建能力，后者是运行状态，二者不能混为一谈。

import sys
import sysconfig

# 构建能力和当前进程状态需要分别读取。
supports_free_threading = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
gil_enabled_now = sys._is_gil_enabled()

print({
    "free_threaded_build": supports_free_threading,
    "gil_enabled_now": gil_enabled_now,
})

如果第一项为真、第二项也为真，通常意味着运行参数主动打开了 GIL，或者依赖栈中有扩展触发了兼容性降级。此时继续跑性能测试没有意义，应先定位状态变化发生在哪次导入之后。

为什么兼容性判断不能只看能否导入

原生扩展需要明确告诉解释器“本模块支持无 GIL 运行”。采用多阶段初始化的模块，应提供 Py_mod_gil 槽并设置 Py_MOD_GIL_NOT_USED；仍使用单阶段初始化的模块，则需要在自由线程构建条件下调用 PyUnstable_Module_SetGIL。没有这个声明，导入行为会以恢复 GIL 的方式优先保证兼容。

因此，导入烟测至少要记录三件事：导入前后的 sys._is_gil_enabled()、是否出现自由线程兼容警告、发生状态变化的具体模块。建议按依赖逐个导入，而不是一次导入整个应用，这样才能把降级点缩小到具体扩展。

旧代码影响：把风险拆成三个层次

纯 Python 包和原生扩展面对的风险不同。内置容器在自由线程构建中具有内部锁，但这只保护容器自身，不会自动保护“先检查、再修改”这样的业务不变量。原生扩展还要额外处理借用引用、结构体字段宏、全局缓存和容器迭代。

需要特别留意三类 C API 用法。第一，直接读取对象结构体字段或依赖不加锁的访问宏；第二，在另一个线程可能修改容器时继续持有借用引用；第三，使用 PyDict_Next 等遍历接口却没有建立临界区。解释器对常见容器操作增加内部保护，不代表扩展自己的多步逻辑天然线程安全。

迁移建议：先声明支持，再审计共享状态

模块支持声明只是入口，不是安全证明。更稳妥的迁移顺序是：先让构建系统产出自由线程扩展，再加入模块声明，随后审计模块级缓存、惰性初始化、对象池、统计计数和第三方 C 库句柄。可变全局状态应使用锁保护，真正按线程隔离的数据可以迁移到线程局部存储。

对于容器访问，尽量使用返回强引用的新接口，缩短裸指针和借用引用跨越的代码范围；涉及多个操作的业务不变量，使用显式锁或 Python 临界区 API。官方文档也明确建议应用层优先使用 threading.Lock 等同步原语，而不是把容器内部锁当作长期兼容契约。

分发侧同样要单列任务。自由线程解释器和扩展模块带有 t ABI 标记，例如 python3.14t；它需要独立 wheel。当前自由线程构建也不支持用 Limited C API 获得稳定 ABI，因此已有的 abi3 发布策略不能原样套用。

最小验证：强制关闭 GIL 跑完整依赖栈

最小验证不要从性能数字开始，而要先证明环境没有静默降级。准备一套自由线程解释器和独立虚拟环境，安装专用 wheel，强制关闭 GIL 后运行导入烟测与完整测试：

# 使用自由线程解释器，并强制本次测试保持 GIL 关闭。
PYTHON_GIL=0 python3.14t -m pytest -q

# 也可以用命令行开关执行同一组测试。
python3.14t -X gil=0 -m pytest -q

通过单元测试后，再加入高并发、长时间和重复初始化场景，重点观察崩溃、数据错乱、重复结果、遗漏结果与内存增长。共享迭代器和跨线程读取正在执行的帧对象也应单独检查，因为它们在自由线程模式下有更严格的安全边界。

最后再测收益。Python 3.14 自由线程构建仍可能付出单线程性能与额外内存成本；只有目标负载能通过 CPU 并行抵消这部分成本，迁移才有业务价值。验收报告至少应同时给出正确性、GIL 状态、wheel 来源、吞吐、尾延迟和内存六项结果。

结论

Python 3.14 把自由线程推进到了可以正式规划迁移的阶段，但“官方支持”不等于“所有扩展自动兼容”。最可靠的判断链是：确认自由线程构建，强制关闭 GIL，逐个导入定位降级，审计扩展共享状态，构建独立 t wheel，最后用并发回归和性能数据验收。只要其中任一环节仍依赖自动恢复 GIL，就应把当前结论标记为“兼容运行”，而不是“自由线程兼容”。