<p>最不踩坑的结论是：用 pybind11 而非手写 PyInit_* 和 PyModuleDef；它自动处理类型映射、模块导出、ABI 兼容性，避免 ImportError、undefined symbol 等常见错误，且需严格匹配模块名、文件名与 PYBIND11_MODULE 宏。</p>
用 pybind11 写 Python 扩展最不踩坑
直接结论：别手写 PyInit_* 和 PyModuleDef，用 pybind11 —— 它把 C++ 类型、函数、异常、STL 容器的映射全包了，且编译链干净，比原生 C API 少写 80% 模板代码。
常见错误现象：ImportError: dynamic module does not define init function（老式 Python 2 风格初始化没适配 Py3.8+）、undefined symbol: _Py_ZeroStruct（链接时漏了 -lpython3.x 或用了系统 Python 而非 venv 中的）。
- 必须用
pybind11_add_module()CMake 函数（不是add_library(... SHARED)手动设），它自动处理导出符号、Python ABI 兼容性、PYBIND11_MODULE宏展开 - 模块名必须和文件名一致（
mylib.cpp→PYBIND11_MODULE(mylib, m)→import mylib），否则ImportError: No module named 'xxx' - 如果 C++ 里抛
std::runtime_error，默认转成RuntimeError；想映射成特定 Python 异常（如ValueError），得用m.attr("ValueError") = py::eval("ValueError")+throw py::value_error("...")
如何暴露 std::vector 和 numpy 数组互操作
这是性能关键点：Python 用户传 list 还是 np.ndarray？C++ 函数该接什么？不统一就频繁拷贝，一调用慢 10 倍。
使用场景：图像处理、数值计算、模型推理等需要零拷贝传递大内存块的场合。
立即学习“Python免费学习笔记（深入）”；
- 暴露
std::vector<float>给 Python，默认转成list（深拷贝）；加.def_readwrite("data", &MyClass::vec, py::return_value_policy::reference)才能返回引用（但注意生命周期！Python 持有后 C++ 对象不能析构） - 要支持
numpy.ndarray输入，用pybind11/numpy.h，声明参数为py::array_t<float>；调用.request()拿到buffer_info，再用static_cast<float*>(buf.ptr)直接访问内存 - 返回
py::array_t<int>时，用py::array_t<int>(shape, data_ptr, parent)构造，传入 C++ 堆内存指针 +parent=py::cast(self)防止提前释放
Windows 下编译失败：LNK2001 / unresolved external symbol PyInit_*
根本原因不是代码写错，而是构建系统没按 Python DLL 导出规则生成模块入口。
参数差异：pybind11 在 Windows 上默认生成 .pyd（本质是 DLL），但要求导出函数名为 PyInit_mymodule，且必须用 /EXPORT:PyInit_mymodule 显式导出（MSVC）或 -Wl,--export-all-symbols（MinGW）。
- CMakeLists.txt 里不能只写
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ...)，必须加set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)（MSVC）或手动写target_link_options(... PRIVATE "/EXPORT:PyInit_mymodule") - 确保 Python 解释器路径和链接的
python3x.lib匹配：用python -c "import sysconfig; print(sysconfig.get_paths()['stdlib'])"确认 Python 版本，再查lib/python3.x/config-3.x-x86_64-linux-gnu/libpython3.x.so（Linux）或libs/python3x.lib（Windows） - VS 编译时关掉
/GL（全程序优化），它会把PyInit_*内联掉导致导出失败
调试段错误：Python 进程在 C++ 模块里 crash
这类问题最难定位，因为 Python 的 traceback 不显示 C++ 栈，gdb 里又卡在 PyObject_Call 里。
性能影响：加日志会掩盖竞态，用 printf 可能因缓冲不刷屏；用 PyErr_SetString 又得手动清异常栈。
- 先开 core dump：
ulimit -c unlimited+gdb python core，然后bt full看 C++ 函数参数和局部变量值 - 在 C++ 函数开头加
if (!PyGILState_Check()) { PyErr_SetString(PyExc_RuntimeError, "GIL not held"); return nullptr; }，避免多线程调用时 GIL 丢失 - 检查所有
py::object是否来自同一 Python 解释器实例（嵌入式场景易出错）；跨线程传递py::object必须用py::reinterpret_borrow<py::object>(obj)+ 手动管理引用计数
最常被忽略的是：C++ 模块里调用的第三方库（比如 OpenCV）是否和 Python 使用的同一套 CRT（Windows）或 libc（Linux）。混用会导致内存分配器不一致，free() 一个 new 出来的指针，当场崩。
