auditwheel repair本质是解决.so跨发行版加载失败，但会强制重写RPATH并打包依赖，可能破坏原有路径逻辑；需用--exclude排除CUDA等库、--no-repair保留原RPATH，并选对manylinux平台标签验证兼容性。
auditwheel 修复 wheel 兼容性，本质是解决动态链接库（.so）在不同 Linux 发行版间因 glibc 版本、系统路径或 RPATH 设置不一致导致的加载失败。它不是“万能补丁”，而是一个有明确边界和副作用的工具——用错地方反而让包更不可靠。
auditwheel repair 会重写 RPATH，但默认行为常破坏原有加载逻辑
你编译的 .so 文件如果依赖 CUDA 运行时（如 libcudart.so.12）或自定义库（如 libcufes.so），原始 RPATH 往往指向相对路径（$ORIGIN/../lib）或项目内目录。而 auditwheel repair 默认会把所有外部依赖拷进 wheel 的 .libs/ 子目录，并把 RPATH 强制改成 $ORIGIN/.libs。这会导致两个问题：
- 原本靠
$ORIGIN/../data/cyfes/找到的libcufes.so突然失效，因为auditwheel把它挪走了 -
libcudart.so.12这类系统级 CUDA 库被强行打包进 wheel，违反 manylinux 策略（auditwheel不应打包非 glibc 的系统共享库） - 修复后
ldd显示依赖路径全变成.libs/，但实际运行时可能仍去系统路径找，引发 symbol not found
解决方法不是禁用 auditwheel，而是控制它“修什么”：
- 用
--exclude排除不该打包的库：auditwheel repair --exclude "libcudart|libcuda|libcufes" -w fix-dist/ dist/*.whl - 用
--no-repair跳过 RPATH 重写，只做兼容性检查：auditwheel show dist/*.whl - 若必须保留原
RPATH，编译时加-Wl,-rpath,'$ORIGIN/../data/cyfes'，再用auditwheel repair --no-deps
manylinux 平台标签不是越新越好，选错就白修
auditwheel repair 的 --plat 参数决定生成的 wheel 文件名和 ABI 兼容范围。常见错误是盲目用 manylinux_2_17 或 manylinux2014：
-
manylinux_2_17要求目标机器 glibc ≥ 2.17，但 CentOS 7 是 2.17，Ubuntu 16.04 是 2.23 —— 表面兼容，实则因符号版本（GLIBC_2.2.5vsGLIBC_2.3）导致运行时报symbol lookup error -
manylinux2014（对应 glibc 2.17）是当前最稳妥的选择，覆盖 CentOS 7+/RHEL 7+ 和主流云镜像 - 如果你的 C++ 扩展用了 C++17 特性或较新的
libstdc++.so.6符号，manylinux2014可能不够，需升级到manylinux_2_28（glibc 2.28，Ubuntu 20.04+）
验证方式很简单：docker run --rm -it quay.io/pypa/manylinux2014_x86_64 ldd ./cyfes/wrapper.cpython-*.so | grep "not found"。找不到就说明平台标签选高了；找到但报 symbol 错误，说明编译时链接了高版本符号。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
auditwheel 不处理 Python C 扩展的 ABI 兼容性，那是编译器的事
auditwheel 只管动态链接层面的库路径和符号可见性，不管 Python C API 层是否兼容。比如你在 Python 3.9 编译的 wrapper.cpython-39-x86_64-linux-gnu.so，即使 auditwheel 修复成功，放到 Python 3.10 环境里仍会报 ImportError: dynamic module does not define module export function。
- 根本原因是 CPython 的 ABI 在 3.8+ 后默认是 per-version（
cp39≠cp310），auditwheel不改这个 - 想做到 ABI 兼容，得用
Py_LIMITED_API编译，生成abi3标签的 wheel（如cp39-abi3-linux_x86_64.whl），但这要求代码不调用非稳定 API - CI 中用
cibuildwheel时，[tool.cibuildwheel.linux] repair-wheel-command必须匹配你实际构建的 Python 版本，不能“一修通用”
真正可靠的修复流程：先检查，再排除，最后验证
别一上来就 auditwheel repair。顺序错了，后面全是坑：
- 第一步：用
auditwheel show dist/*.whl查看原始 wheel 依赖哪些系统库，哪些已打包，哪些缺失 - 第二步：对 CUDA、ROCm、自定义
.so等非 glibc 库，加--exclude；对libgcc_s.so.1、libstdc++.so.6等编译器运行时，让它自动打包 - 第三步：修复后进 manylinux 镜像跑
python -c "import cyfes; print(cyfes.__version__)"，而不是只看pip install是否成功 - 第四步：用
patchelf --print-rpath检查关键.so的RPATH是否符合预期（比如仍是$ORIGIN/../data/cyfes而非全被改成.libs）
最易被忽略的一点：很多项目把 libcufes.so 放在 data/ 目录下，靠 setup.py 的 data_files 安装到 site-packages 外部路径，但 auditwheel 只扫描 packages 内的 .so。这种结构下，auditwheel 根本看不到它，也就不会修复或排除——结果运行时直接 lib not found。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
