Python.h缺失的根本原因是未安装Python开发包，Linux需装python3-dev、macOS用brew install python、Windows需勾选开发组件；验证用python3-config --includes，编译须加-I路径，链接需-lpython3.x并正确设置sys.path与GIL。
Python.h头文件找不到或编译失败
这是最常见拦路虎：C++项目根本没法开始调用Python C API。根本原因不是没装Python，而是没装python3-dev（Linux/macOS）或Python Development Bundle（Windows）。Ubuntu上只装python3包是不够的，Python.h在开发包里。
验证方法：运行python3-config --includes，看输出是否含-I/usr/include/python3.x路径；若报command not found，说明开发包缺失。
- Ubuntu/Debian：
sudo apt install python3-dev - macOS（Homebrew）：
brew install python3（默认带头文件） - Windows（官方安装包）：安装时勾选
Add Python to PATH和Download debug binaries，再手动确认Include目录存在（如C:UsersXAppDataLocalProgramsPythonPython311include） - CMake中链接时，必须用
find_package(Python3 REQUIRED COMPONENTS Interpreter Development)，不能只找Interpreter
Py_Initialize()后调用PyRun_SimpleString失败
看似初始化成功，但执行print("hello")却没输出，或直接崩溃——大概率是Python解释器没正确初始化运行时路径，导致找不到builtins模块。
Py_Initialize()本身不自动设置sys.path，尤其当你的C++程序不在Python安装目录下运行时，import会失败，连print都可能因底层依赖缺失而挂掉。
立即学习“Python免费学习笔记（深入）”；
- 务必在
Py_Initialize()之后立即调用PyRun_SimpleString("import sys; sys.path.append('.')")，确保当前目录可导入 - 更稳妥做法：用
PySys_SetPath()显式设置完整路径，例如PySys_SetPath(L"/usr/lib/python3.11:/usr/lib/python3.11/lib-dynload")（路径需根据python3 -c "import sys; print('\n'.join(sys.path))"输出调整） - 避免在多线程环境未加
PyGILState_Ensure()就调用Python C API，否则随机崩溃
从C++传参给Python脚本并获取返回值
用PyRun_SimpleString()只能执行无输入无输出的脚本，真要交互就得用PyRun_String()配合Python对象操作。核心是构造PyObject*参数、执行、提取结果。
比如C++里有个int x = 42，想传进Python做x * 2再拿回来：
PyObject* main_module = PyImport_AddModule("__main__");
PyObject* main_dict = PyModule_GetDict(main_module);
PyObject* x_obj = PyLong_FromLong(42);
PyDict_SetItemString(main_dict, "x", x_obj);
<p>// 执行表达式，返回PyObject<em>
PyObject</em> result_obj = PyRun_String("x * 2", Py_eval_input, main_dict, main_dict);
long result = PyLong_AsLong(result_obj);</p><p>Py_DECREF(x_obj);
Py_DECREF(result_obj);</p>-
Py_eval_input用于表达式求值，Py_file_input用于完整脚本，别混用 - 所有
PyLong_FromXxx、PyRun_String返回的对象都必须Py_DECREF，否则内存泄漏（Python引用计数不会自动清理C++侧创建的临时对象） - 字符串传入要用
PyUnicode_FromString()，且注意编码：UTF-8安全，GBK等可能出错
Python脚本中抛异常，C++如何捕获并处理
Python脚本里raise ValueError("bad input")不会让C++程序退出，但PyRun_SimpleString()会静默吞掉异常。必须主动检查并转换为C++可处理的形式。
关键函数是PyErr_Occurred()——只要它返回非NULL，就说明有未处理异常。接着用PyErr_Fetch()取出异常类型、值、traceback三元组。
- 执行完Python代码后，立刻检查：
if (PyErr_Occurred()) { ... } - 用
PyErr_Print()可直接打印到stderr（调试用），但生产环境应提取错误信息：PyUnicode_AsUTF8(PyObject_Str(exc_value)) - 不要在异常未清空时继续调用其他Python C API，否则后续调用可能失败或行为未定义
- 清理异常状态必须调用
PyErr_Clear()，否则下次检查仍会返回true
C++嵌Python不是“调个库”那么简单，真正卡住的从来不是语法，而是Python解释器生命周期管理、GIL控制、引用计数和路径配置这四点。尤其在动态加载.so/.dll、或Python版本混用（如系统Python 3.9 vs 应用自带3.11）时，PySys_GetPath()返回的路径和实际模块位置对不上，问题会非常隐蔽。
