python头文件与链接库版本必须严格匹配，PyRun_SimpleString不支持中文路径或空格，多线程需手动管理GIL，Py_Finalize不可重复调用，c++容器需手动转换为Python对象。
Python.h 头文件和链接参数必须匹配 Python 版本
调用 Python 脚本前，C++ 程序必须链接到正确的 Python C API 库。常见错误是 python3.9 头文件配 libpython3.8.so，导致运行时崩溃或 Py_Initialize 失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
python3-config --includes获取头文件路径，python3-config --ldflags获取链接参数（注意它可能不含-lpython3.x，需手动补全） - linux 下检查
libpython3.x.so是否在LD_LIBRARY_PATH中，或用patchelf修改 RPATH - macos 需额外链接
-framework Python或指定-lpython3.x并确保DYLD_LIBRARY_PATH正确 - windows 上优先用
python39.lib（非 DLL 导入库），且运行时 Python DLL 必须在 PATH 中
PyRun_SimpleString 不能直接传含中文路径或带空格的脚本名
PyRun_SimpleString 是最简调用方式，但只适合执行纯 Python 代码字符串，不适用于加载外部 .py 文件——尤其当路径含中文、空格或需要传递命令行参数时，会因字符串解析失败而静默退出或报 SyntaxError。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 改用
PyRun_String+Py_file_input模式，先用PyFile_FromString打开脚本文件对象，再执行 - 更稳妥的做法是调用
PyImport_ImportModule导入模块后调用其函数，避免路径解析问题 - 若必须用路径，先用
PyUnicode_DecodeFSDefault转义路径字符串，再传给PyRun_SimpleFileExFlags - 调试时加
PyErr_Print()，否则异常会被吞掉
多线程下必须管理 GIL，且 Py_Finalize 不可多次调用
C++ 主线程启动 Python 后，若在子线程中调用 Python API（如从 qt worker Thread 调脚本），不处理 GIL 会导致段错误；而反复调用 Py_Finalize（比如每次调用后都清理）会破坏解释器状态，后续 Py_Initialize 失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 子线程中先调
PyGILState_Ensure()，执行完 Python 调用后立即PyGILState_Release() - 整个进程生命周期内只做一次
Py_Initialize/Py_Finalize，不要在循环或频繁调用中反复初始化 - 若需隔离执行环境（如防脚本污染全局命名空间），用
PyThreadState_New创建独立线程状态，而非重启解释器 - 注意：Python 3.12+ 已弃用
Py_Finalize，应改用Py_EndInterpreter+PyThreadState_Get配合销毁
传递复杂数据（如 vector）需手动转换为 Python 对象
C++ 的 std::vector、std::map 无法自动转成 Python list/dict，直接传指针会触发类型错误或内存越界。常见做法是手写转换逻辑，但容易漏掉引用计数或编码转换。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 字符串向量转
PyList_New(n)，对每个std::string用PyUnicode_FromString（ASCII 安全）或PyUnicode_FromStringAndSize（支持二进制/UTF-8） - 嵌套结构建议封装为
PyObject*构造函数，避免在业务逻辑里混杂 API 调用 - 接收 Python 返回值时，用
PyList_Size/PyList_GetItem取元素，注意返回的是 borrowed reference，需Py_INCREF再保存 - 性能敏感场景慎用
PyRun_String传大量数据，改用 C API 构建对象后调用函数更高效
C++ 调 Python 的坑不在语法，而在生命周期、线程模型和内存所有权的隐式约定。哪怕只多调了一次 Py_Finalize，或少了一个 Py_DECREF，都可能让程序在某个特定输入下崩溃，而且很难复现。