Python 3.14 升级后怎样检查扩展模块兼容

Python 3.14 升级后检查扩展兼容，我会先确认解释器构建与目标平台，再检查包的安装条件，接着逐个导入实际扩展，最后用项目的小型功能样本验收。能安装、能导入、功能正确是三种不同的结论，不能只看 pip 没有报错。

下面做一个单文件导入探测器：它给每个指定模块启动独立子进程，保留退出码、错误文本和 GIL 状态。示例用于读者自己的升级环境，文中没有声称已在某个业务项目跑通。

Python 官方入口：https://www.python.org/

Python 3.14 迁移文档：https://docs.python.org/3.14/whatsnew/3.14.html

把目标缩小到一份可解释的兼容记录

我更倾向于先回答“哪个具体模块、在哪种解释器上失败”，而不是直接列一张“支持 Python 3.14”的包名表。一个发行包可能含多个扩展，也可能在首次调用某个功能时才加载原生库。只导入顶层包，容易漏掉真正的问题位置。

Python 3.14 的迁移文档列出了 C API 的变化与移除项。例如仍依赖被移除接口的自有扩展，需要回到构建日志和对应源码处理，而不是简单重命名二进制文件。本文不根据一个文件后缀推断所有扩展都要重编译。

建立干净的 Python 3.14 试验环境

保留旧解释器和旧环境，在新环境按受控依赖清单重新安装。我不建议把旧环境的 site-packages 直接复制过来：这样既混淆安装来源，也让排查时无法判断到底是谁选择了二进制分发包。以下是 Unix/macOS 的命令示例；Windows 请使用对应虚拟环境的 Scripts\python.exe。

# 在 Unix/macOS 上用目标解释器建独立环境，保留旧环境供对照。
python3.14 -m venv .venv314
.venv314/bin/python -m pip install --upgrade pip
# requirements.txt 应来自本项目受控依赖清单，不复制旧 site-packages。
.venv314/bin/python -m pip install -r requirements.txt
# 保存解释器支持的安装标签，人工阅读，不把输出格式当稳定接口。
.venv314/bin/python -m pip debug --verbose
# 这里只检查已安装包声明的依赖关系。
.venv314/bin/python -m pip check

wheel 的兼容标签由 Python、ABI 和平台三部分组成。cp314 只是其中一个维度；架构和操作系统条件仍要匹配。使用稳定 ABI 的分发包可能以较早的 Python 标签支持较新的普通 CPython，因此不要只按文件名是否含“314”筛选。

pip debug 的输出用于排查，官方提示其选项与输出尚不保证稳定，不宜用固定列号解析成长期生产接口。pip check 检查安装包声明的依赖是否匹配，不会替你导入每个扩展或执行其业务功能。

写一个逐模块启动子进程的探测器

把下面代码保存为 probe_imports.py。我让每个模块使用独立进程，是为了让某个模块发生原生崩溃时，主程序仍有机会继续记录其他模块；这不是安全沙箱。模块导入会执行初始化代码，只应使用自己信任的依赖清单。

import argparse
import json
import platform
import re
import subprocess
import sys
import sysconfig

# 子进程只导入显式指定的模块；不把模块名拼接成可执行源码。
WORKER = """
import importlib
import json
import sys
read_gil = getattr(sys, "_is_gil_enabled", lambda: None)
before = read_gil()
module = importlib.import_module(sys.argv[1])
spec = getattr(module, "__spec__", None)
print(json.dumps({
    "module": sys.argv[1],
    "origin": getattr(spec, "origin", None),
    "loader": type(getattr(spec, "loader", None)).__name__,
    "gil_before": before,
    "gil_after": read_gil()
}, ensure_ascii=False))
"""


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("modules", nargs="+")
    args = parser.parse_args()
    # 限制为普通点分模块名，导入对象应来自自己信任的依赖清单。
    for name in args.modules:
        if not re.fullmatch(r"[A-Za-z_]\w*(\.[A-Za-z_]\w*)*", name):
            parser.error("请输入点分模块名")

    report = {
        "environment": {
            "executable": sys.executable,
            "python": platform.python_version(),
            "machine": platform.machine(),
            "platform": sys.platform,
            "soabi": sysconfig.get_config_var("SOABI"),
            "free_threaded_build": bool(
                sysconfig.get_config_var("Py_GIL_DISABLED")
            ),
        },
        "imports": [],
    }
    failed = False
    for name in args.modules:
        try:
            # 同一解释器、每模块独立进程；-I 排除当前目录和用户站点干扰。
            proc = subprocess.run(
                [sys.executable, "-I", "-c", WORKER, name],
                capture_output=True, text=True, encoding="utf-8",
                errors="replace", timeout=20, check=False,
            )
        except subprocess.TimeoutExpired:
            failed = True
            report["imports"].append({
                "module": name, "status": "timeout",
            })
            continue
        failed = failed or proc.returncode != 0
        # 保留原始输出，兼容模块自身向标准输出写入文本的情况。
        report["imports"].append({
            "module": name,
            "status": "import-ok" if proc.returncode == 0 else "process-failed",
            "returncode": proc.returncode,
            "stdout": proc.stdout,
            "stderr": proc.stderr,
        })
    print(json.dumps(report, ensure_ascii=False, indent=2))
    return 1 if failed else 0


if __name__ == "__main__":
    # 退出码只表达导入探测情况，不代表业务功能已验收。
    raise SystemExit(main())

这份记录包含 SOABI、构建时是否启用自由线程，以及子进程导入前后的 GIL 状态。sys._is_gil_enabled 是 CPython 的实现细节，脚本用兜底函数处理其他实现不存在它的情况。origin 和加载器名称帮助定位实际加载对象；顶层包可能仍是 Python 文件，应继续列入维护者文档标明的底层扩展模块。

-I 用来减少当前目录、用户站点和 Python 环境变量带来的路径干扰；它仍能使用该虚拟环境内已安装的包。尚未安装、只依赖当前源码目录才能导入的项目，先按项目文档安装到环境，再进行这种探测。子进程仍继承其他系统环境，不能因此声称完全隔离了动态库搜索路径。

运行探测后按故障层次判断

# 将上面的代码保存为 probe_imports.py；示例名称均为标准库模块。
.venv314/bin/python probe_imports.py _ssl _sqlite3 _decimal > imports-314.json
# 随即查看退出码；报告中仍需逐项阅读 stderr 和 origin。
echo $?

_ssl、_sqlite3、_decimal 只是便于说明的标准库扩展名字，不代表它们一定在每个自定义 Python 构建中存在。实际使用时，将名称替换为本项目确定需要的模块。报告可能含安装目录和系统错误详情，分享前先脱敏。

代码不会把 stderr 非空直接算作导入失败，因为警告和其他诊断也可能写入该通道。即使退出码为零，也应阅读警告。它用内存捕获输出，适合受控的小清单；输出特别多、会创建子孙进程或依赖外部交互的模块，需要项目专门的进程管理方案。

把普通构建与自由线程构建分开接入

Python 3.14 的自由线程构建应单独建立依赖环境和结果记录。官方扩展适配文档说明，这类 C 扩展需要专门构建；3.14 的自由线程构建不支持 Limited C API 或稳定 ABI，不能把普通构建的 abi3 分发包直接当作它的兼容凭据。

扩展如果没有声明支持无 GIL 运行，导入时通常会发出警告并启用 GIL。因此，导入成功和“保持无 GIL”也要分别看。脚本中的 gil_before 与 gil_after 只表示当前子进程的观测；如果启动前 GIL 已启用，不能借这两个字段推断扩展的无 GIL 安全性。不要为了让探测结果好看而强制关闭 GIL。

部署时，我会把解释器、依赖清单、原生库版本与探测记录一起绑定到同一个镜像或环境。新环境出问题时切回仍保留的旧环境，比在原环境里反复覆盖安装更容易解释。模块功能验收要选择实际用到的小样本，例如编解码往返、数值计算误差范围或数据库参数绑定；涉及网络和外部系统的用例应使用项目提供的测试资源。

什么时候可以结束这次升级检查

我会把完成条件写成具体交付项：目标解释器身份已确认；所需发行包有明确安装来源；实际扩展导入记录可解释；关键功能样本通过；需要自由线程时，另有并发验收和供应方支持说明。导入探测器适合做第一轮筛选，不能替代项目测试套件。

没有 Python 3.14 wheel 就一定不能用吗？

不一定。可能存在匹配的稳定 ABI 分发包，或者项目支持从源码构建。是否适合当前环境，仍需看供应方支持范围、构建依赖和后续功能验收，不能只根据一次安装失败下结论。

修改扩展文件名能解决 ABI 问题吗？

不能。改名不会改变文件内部的二进制接口、目标架构或动态链接依赖。应选择适用的分发包或按维护者支持的方法重新构建。

为什么顶层包能导入，具体功能仍失败？

顶层包可能没有立即加载所有原生扩展或外部库。把实际调用路径中的底层模块和功能样本加入项目清单，才能缩小这一盲区。

参考资料：安装标签：https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/；自由线程扩展：https://docs.python.org/3.14/howto/free-threading-extensions.html；GIL 观测接口：https://docs.python.org/3.14/library/sys.html；pip 调试与依赖检查：https://pip.pypa.io/en/stable/cli/pip_debug/、https://pip.pypa.io/en/stable/cli/pip_check/。