Python.h缺失需安装开发包并配置路径；Py_Initialize后须手动添加sys.path；传参用PyUnicode_FromString等转换并管理引用计数；多线程需PyGILState_Ensure/Release。
Python.h 头文件找不到或编译失败
直接 #include 报错“no such file or directory”，通常是因为没装 Python 开发头文件，或者 C++ 编译器找不到 Python 安装路径。
- Linux/macOS：安装
python3-dev（Debian/Ubuntu）或python3-devel（CentOS/RHEL），macOS 用brew install python后头文件默认在/opt/homebrew/include/python3.x/或/usr/local/include/python3.x/ - Windows：用官方 Python 安装包时，
Python.h在PythonXX\include\目录下，需手动把该路径加进 C++ 项目的包含目录（如 VS 的Additional Include Directories） - 务必确认 C++ 工程使用的架构（x64 / x86）和 Python 解释器一致，否则链接时会报
LNK2001: unresolved external symbol Py_Initialize类错误
Py_Initialize() 后无法 import 模块
调用 Py_Initialize() 成功，但 PyRun_SimpleString("import sys; print(sys.path)") 显示路径为空或不包含你的脚本目录，导致 import 失败。
- 必须在
Py_Initialize()后立即调用PyRun_SimpleString("import sys; sys.path.append(r'/your/script/path')")，注意 Windows 路径用原始字符串（r""）或双反斜杠 - 不要依赖默认
sys.path—— 嵌入式调用下它往往只含空字符串或极简路径，Py_SetPythonHome()可设 Python 根目录，但更稳妥的是显式追加 - 若模块含 C 扩展（如
numpy），还需确保对应 .pyd/.so 文件能被动态加载（PATH/LD_LIBRARY_PATH 包含 Python DLL 所在目录）
从 C++ 传参给 Python 函数并获取返回值
用 PyObject_CallObject() 调用 Python 函数时，参数打包和类型转换容易出错，尤其是字符串、列表、自定义对象。
- 字符串：C++
std::string s = "hello"→ PythonPyObject* arg = PyUnicode_FromString(s.c_str())；不能直接传const char*给PyObject_CallObject - 多个参数：用
PyTuple_New(n)创建元组，再用PyTuple_SetItem(tuple, i, obj)填充（注意SetItem会接管引用计数，传入后原obj不再 owns 引用） - 接收返回值：检查是否为
nullptr（异常），再用PyLong_AsLong()、PyFloat_AsDouble()、PyUnicode_AsUTF8()等安全转换；避免直接强转指针 - 别忘了调用
Py_DECREF()释放临时PyObject*，否则内存泄漏（尤其在循环中反复调用时）
多线程下 PyGILState_Ensure() 和 GIL 释放
C++ 主线程启动 Python 后，若另起 std::thread 执行 Python API，不处理 GIL 会崩溃或卡死。
立即学习“Python免费学习笔记（深入）”；
- 每个新线程首次调用 Python C API 前，必须先调用
PyGILState_STATE state = PyGILState_Ensure()；退出前调用PyGILState_Release(state) - 主线程若长期持有 GIL（比如执行长时间 Python 计算），可用
Py_BEGIN_ALLOW_THREADS/Py_END_ALLOW_THREADS宏临时释放，让其他 C++ 线程能进入 Python - 切勿在未持有 GIL 时调用任何 Python C API（除了少数标记为 thread-safe 的函数，如
PyThreadState_Get()）
C++ 调用 Python 的核心难点不在初始化，而在生命周期管理：Python 解释器状态、对象引用计数、GIL 切换、路径与模块加载上下文——这些环节任一遗漏，都会表现为静默失败或段错误，且难以调试。
