根本原因是CMake无法定位目标平台的Python开发头文件和库路径，尤其交叉编译时宿主机路径无效；需显式指定PYTHON_EXECUTABLE、INCLUDE_DIR、LIBRARY，并确保三者版本、架构、构建选项完全一致。
pybind11编译失败：找不到Python头文件或库路径
常见报错是 CMake Error: Could not find PythonInterp 或 fatal error: Python.h: No such file or directory。根本原因是 CMake 没法定位到目标平台的 Python 开发头文件和链接库——尤其是交叉编译时，宿主机（如 x86_64 Linux）的 Python 路径完全不能用。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 显式传入
-DPYTHON_EXECUTABLE、-DPYTHON_INCLUDE_DIR、-DPYTHON_LIBRARY三个变量，全部指向目标平台的 Python 构建产物（例如 aarch64 的python3.9-config --includes输出路径） - 确保目标平台 Python 是从源码编译的（非系统包管理器安装），否则
Python.h和静态/动态库可能缺失或架构不匹配 - 若用
find_package(Python COMPONENTS Interpreter Development)，需配合CMAKE_FIND_ROOT_PATH指向目标 sysroot，并设CMAKE_FIND_ROOT_PATH_MODE_* = ONLY
交叉编译时 pybind11 生成的 .so 无法被 Python import
典型现象是 ImportError: /path/to/module.cpython-39-aarch64-linux-gnu.so: cannot open shared object file: No such file or directory，或更隐蔽的 undefined symbol: PyUnicode_FromString。这通常不是路径问题，而是 ABI 不兼容或符号未正确导出。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确认 pybind11 编译时启用了
-DPYBIND11_PYTHON_VERSION=3.9（与目标 Python 版本严格一致），且 CMake 工具链中CMAKE_SYSTEM_PROCESSOR设置正确（如aarch64） - 检查生成的模块是否含 RPATH：
readelf -d module.so | grep RPATH；若为空，需加-DCMAKE_INSTALL_RPATH=$ORIGIN并在链接时用-Wl,-rpath,$ORIGIN - 避免使用
pybind11_add_module()默认的SHARED类型，改用MODULE（它会自动禁用-fPIC冲突并设置正确后缀）
Windows 上用 MSVC 交叉编译到 ARM64 Python 扩展
Visual Studio 2019+ 支持 ARM64 工具集，但 pybind11 默认不识别 ARM64 架构宏，会导致 PyInit_* 符号名错误或 __declspec(dllexport) 失效。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在 CMake 配置中强制指定
-A ARM64（MSVC 的 platform 参数），并添加-DMSVC_ARM64=ON以启用 pybind11 的 ARM64 补丁逻辑 - 手动在模块入口前加
#define PYBIND11_MODULE_NAME your_module_name，防止 MSVC 预处理器把PyInit_展开成带下划线的畸形符号 - 链接时必须包含
python39.lib（而非python39_d.lib），且确保该 .lib 是 ARM64 版本（可通过dumpbin /headers python39.lib验证机器类型）
如何验证交叉编译后的模块真正在目标平台运行
别只依赖 file module.so 显示 “aarch64” 就认为成功——很多工具链会伪造架构标识。真实校验必须在目标环境执行。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
adb shell（Android）或ssh（Linux ARM 设备）登录后，直接运行python3 -c "import your_module; print(your_module.__file__)" - 若报
Illegal instruction，说明 CPU 指令集不匹配（如编译时用了+crypto但目标 CPU 不支持），需在 CMake 中加-march=armv8-a等保守选项 - 用
ldd module.so检查所有依赖是否可解析，特别注意libpython3.9.so是否指向目标平台的绝对路径（而非宿主机路径）
交叉编译 pybind11 模块最易被忽略的是 Python 运行时 ABI 的隐式绑定：CMake 找到的 Python 解释器、头文件、库文件，三者必须来自同一构建，且版本、架构、构建选项（如 UCS2/UCS4、debug/release）完全一致。差一个字节，import 就会在符号表层级静默失败。
