Python 3.15 的 abi3t 与 cp315t wheel 如何选择

给 CPython C 扩展选择 wheel 标签时，不能只看“是不是 Python 3.15”。真正要先回答的是：扩展要支持普通的 GIL-enabled 构建、free-threaded 构建，还是两者都支持；源代码是否已经符合对应的 Limited API；当前构建工具能不能正确生成标签。

能迁移到 Python 3.15 的 abi3t 并且希望一份 wheel 覆盖两类 CPython 构建时，使用 cp315-abi3.abi3t-平台标签；工具链还不支持 abi3t 或代码暂时无法迁移时，面向 3.15 free-threaded 构建选择 cp315t，不要把它误写成稳定 ABI。

先区分 abi3t、abi3 与 cp315t 的兼容目标

Python wheel 文件名的核心格式是 {python tag}-{abi tag}-{platform tag}。这里最容易混淆的是 Python 标签和 ABI 标签并不表达同一件事：cp315 表示 CPython 3.15 这个最低实现版本，abi3.abi3t 则说明扩展使用稳定 ABI，并同时覆盖非 free-threaded 与 free-threaded 构建。

因此，扩展只支持普通 CPython 时继续用 abi3；必须支持 free-threaded、但尚未能进入 abi3t 时，构建 cp315t；只有源代码和构建链都准备好时，才把目标写成 abi3.abi3t。

确认扩展源代码能否进入 abi3t 的 Limited API

abi3t 不是改 wheel 文件名就能获得的承诺。Python 3.15 文档说明，它有比 abi3 更严格的 API 限制，扩展通常需要改用适合 free-threading 的 C API。直接定义 Py_TARGET_ABI3T 只能让头文件暴露目标 API，不能替代源代码迁移。

#define Py_LIMITED_API 0x030C0000 /* 中文说明：示例把普通稳定 ABI 的最低版本设为 3.12 */
#define Py_TARGET_ABI3T 0x030F0000 /* 中文说明：同时声明面向 Python 3.15 的 free-threaded 稳定 ABI */
#include                 /* 中文说明：两个宏必须放在 Python.h 之前 */

static int module_ready(void) {
    return 1; /* 中文说明：真实扩展应在这里完成受限 API 允许的初始化工作 */
}

迁移前重点检查四处：是否仍把 PyObject 作为自定义实例结构的内嵌首字段；是否需要用负的 PyType_Spec.basicsize 表示额外数据；是否采用多阶段初始化和新的模块导出方式；是否依赖不在 Limited API 内的 CPython 内部细节。尤其是可继承的自定义类型，不能随意用 Py_TYPE(obj) 取得类型数据，类型对象边界必须和代码设计一致。

如果扩展由 Cython、PyO3 或其他生成器维护，还要先看生成器和构建工具是否已经提供 abi3t 支持。没有支持时，选择 cp315t 或继续发布 abi3，比写出一个不真实的稳定 ABI 标签更稳妥。

构建工具不支持时选择 cp315t

Python 3.15 的变更说明把两条路分得很清楚：能迁移的扩展应由 Setuptools、meson-python、scikit-build-core、Maturin 等构建工具选择 abi3t；工具尚未支持时，先单独编译 cp315t。这不是降低标签要求，而是诚实地声明“只针对这个版本的 free-threaded ABI”。

# 中文说明：以下是标签形状示例，不是要求所有项目手写文件名
demo-1.0-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
demo-1.0-cp315-cp315t-manylinux_2_28_x86_64.whl

第一行的 cp315 是最低 Python 版本，abi3.abi3t 是压缩后的双 ABI 标签；第二行的 cp315t 是版本专用 ABI，平台标签仍要按实际构建平台填写。不要把 cp315t 改成 abi3.abi3t 来扩大安装范围，安装器只负责匹配标签，不会替你证明二进制真的满足稳定 ABI。

用文件名和双运行时测试收尾

发布前可以按下面的顺序检查，但检查对象是构建产物与支持声明，不是“文件名看起来像不像”。先确认 Python 标签不低于扩展实际使用的最低版本，再确认 ABI 标签与编译宏或工具配置对应，最后确认平台标签与架构、libc 或 macOS 最低版本一致。

1. 目标核对：free-threaded 运行时要能识别 abi3t 或 cp315t，普通构建对双 ABI wheel 也应能回退到 abi3t。
2. 导入核对：在 CPython 3.15 free-threaded 和普通 CPython 3.15 环境分别安装；需要覆盖更高版本时，再在目标版本测试。
3. 行为核对：稳定 ABI 只保证 ABI 兼容，不保证所有行为都不会变化，扩展自己的测试仍要覆盖线程状态、引用计数和异常路径。

如果两类环境都要支持，优先把发布矩阵设计成“每个平台一份 abi3.abi3t wheel”，再为性能或暂时无法迁移的扩展保留版本专用 cp315t。这能让兼容承诺、构建成本和测试范围保持一致。

常见问题

只设置 Py_TARGET_ABI3T 就能发布 abi3t 吗？

不能。它只是选择头文件暴露的目标 ABI，源代码、模块初始化、类型数据访问、构建工具和文件标签仍需一起满足要求。

cp315t 能安装到普通 Python 3.15 吗？

不要把它当成可泛化承诺。cp315t 是 3.15 free-threaded 的版本专用 ABI；需要两类构建共用一份 wheel 时，应完成迁移并使用 abi3.abi3t。

abi3t 是否意味着所有 Python 版本都能用？

不是。Python 标签仍给出最低版本，平台标签也必须匹配；此外还要按文档建议在每个支持的 CPython 版本和两种构建上测试。