Python 3.14 free-threaded 构建选择前要检查哪些扩展兼容性

Python 3.14 的 free-threaded 构建已经从实验选项变成正式支持的可选构建，但切换它并不是把解释器换成带 t 的文件名那么简单。真正要检查的是三层：当前解释器是否具备无 GIL 能力，依赖是否提供对应 ABI 的二进制包，以及 C 扩展是否明确声明自己能在 GIL 关闭时运行。

Python 3.14t 先确认解释器和运行状态

先不要看业务压测，运行下面这段最小检查。构建能力和运行状态必须分开记录：前者决定能不能尝试，后者决定这次测试到底有没有测到无 GIL。

import sys
import sysconfig

# 先确认解释器版本、ABI 标识和构建能力。
print(sys.version)
print("build_supports_free_threading =", sysconfig.get_config_var("Py_GIL_DISABLED"))
print("abiflags =", sys.abiflags)

# 这是运行时状态；False 才表示当前进程的 GIL 已关闭。
print("gil_enabled =", sys._is_gil_enabled())

如果配置变量是 1，说明解释器按 --disable-gil 构建；sys.abiflags 通常能看到 t。但导入一个未适配的 C 扩展后，CPython 可能重新启用 GIL，所以最后一行要放在关键依赖导入之后再看一次。PYTHON_GIL=1 可用于对照测试，PYTHON_GIL=0 则要求解释器本身支持该构建。

先看 wheel 标签，再看模块初始化声明

纯 Python 包通常可以继续使用 py3-none-any；风险集中在包含共享库的包。检查发布文件名时，重点看 Python/ABI/platform 三段标签，free-threaded 构建需要专用的 t ABI。不要因为 pip 找到了一个能解压的 wheel，就认定它能安全并行运行。

扩展初始化也要看源码。多阶段初始化应提供 Py_mod_gil 槽；单阶段初始化则要在 free-threaded 构建下调用 PyUnstable_Module_SetGIL()。支持旧版本时，用 PY_VERSION_HEX 做条件编译，避免普通构建找不到新符号：

static struct PyModuleDef_Slot module_slots[] = {
    /* 只在支持该槽的 Python 版本声明无 GIL支持。 */
    #if PY_VERSION_HEX >= 0x030D0000
        {Py_mod_gil, Py_MOD_GIL_NOT_USED},
    #endif
        {0, NULL}
};

这段声明只回答“模块允许在无 GIL 下加载”，不替代对内部状态的审查。真正的线程安全仍然要由扩展作者保证。

C 扩展代码里检查哪些并发危险点

迁移时优先搜下面五类代码。以前由 GIL 间接保护的全局缓存、静态可变对象和单例状态，现在需要锁或线程局部存储；可变容器上的借用引用和无检查宏，也不能只凭“CPython 以前一直能跑”来判断。

• 共享状态：全局缓存用扩展自己的互斥机制保护，或者在无 GIL 构建中关闭非必要缓存。
• 借用引用：列表、字典可能被其他线程修改时，优先改用返回强引用的 API，例如 PyList_GetItemRef()。
• 容器遍历：PyDict_Next() 不会替字典加锁；必要时用匹配的 Py_BEGIN_CRITICAL_SECTION 和 Py_END_CRITICAL_SECTION。
• 内存分配：Python 对象使用 object 分配域，普通缓冲区不要误用 PyObject_Malloc()，应检查是否应改为 PyMem_Malloc()。
• 线程状态：扩展自己创建的线程仍需通过 PyGILState_Ensure() 等 API 获得有效线程状态；无 GIL 不等于可以无条件调用 Python C API。

/* 可变字典的遍历需要明确保护范围；不要假设 GIL 会替你加锁。 */
Py_BEGIN_CRITICAL_SECTION(dict_obj);
Py_ssize_t pos = 0;
while (PyDict_Next(dict_obj, &pos, &key, &value)) {
    /* 这里只做不阻塞的检查，避免把外部 I/O 放进保护区。 */
}
Py_END_CRITICAL_SECTION();

用强制无 GIL 测试决定是否切换

最后做一次可重复的隔离测试，而不是只执行 import。在新虚拟环境中安装依赖，先用 PYTHON_GIL=0 启动测试，再检查导入警告、并发读写、异常处理、资源释放和进程退出。对照组可以用 PYTHON_GIL=1 跑相同用例，帮助区分业务竞态和构建差异。

# 用隔离环境测试，避免污染默认解释器。
python -m venv .venv-ft
source .venv-ft/bin/activate
python -m pip install -U pip

# 强制保持无 GIL；只对支持 --disable-gil 的解释器有效。
PYTHON_GIL=0 python -W error::RuntimeWarning -m pytest -q

# 再确认关键扩展导入后没有让 GIL 回来。
PYTHON_GIL=0 python -c 'import sys, your_extension; print(sys._is_gil_enabled())'

如果只在有 GIL 的对照组通过，先回到扩展源码和 wheel 标签，不要急着给业务代码加锁。若无 GIL 组稳定通过，再以小流量、可回滚的方式观察吞吐、内存和异常率；free-threaded 构建有额外运行时开销，不是所有工作负载都会自动变快。

常见问题

看到 abi3 就代表支持 free-threaded 吗？

不代表。abi3 解决的是传统 Stable ABI 的跨版本问题，free-threaded 构建仍需要专用的 t 构建与适配声明。

扩展导入后 GIL 被重新启用，程序还能用吗？

可以运行，但这次进程已经不能按“无 GIL 并行”评估。把警告当作迁移信号，确认扩展版本或源码适配后再测。

Windows 从源码编译为什么还要额外设置宏？

Python 官方说明 Windows 安装器存在限制，源码构建扩展时可能需要手动定义 Py_GIL_DISABLED=1，否则构建侧识别不到 free-threaded 模式。