C++怎么嵌入Python解释器-C++-PHP中文网

Py_Initialize()常失败的根本原因是Python解释器找不到标准库路径和启动配置，需在调用前用Py_SetPythonHome()或Py_SetPath()显式指定Python安装根目录或模块搜索路径。

c++怎么嵌入python解释器

为什么直接调用 `Py_Initialize()` 常常失败

多数人第一次尝试嵌入时，Py_Initialize() 看似成功，但后续调用 PyRun_SimpleString("print('hello')") 却静默无输出，或报 ImportError: No module named 'encodings'。根本原因不是 C++ 代码写错了，而是 Python 解释器没找到自己的标准库路径和启动配置。

关键点在于：Python 嵌入不是“拿来即用”，它默认按系统安装路径查找 python3X.zip、lib/python3X/ 和 lib/python3X/site-packages/。如果你没显式设置，而只是链接了 libpython3.x.so（Linux）或 python3x.dll（Windows），解释器会找不到内置模块。

必须在 Py_Initialize() 前调用 Py_SetPythonHome() 或 Py_SetPath()，明确告诉解释器“你的家在哪”
Py_SetPythonHome() 接收的是 Python 安装根目录（如 /usr 或 C:\Python39），不是 lib 子目录
更稳妥的做法是用 Py_SetPath() 直接传入完整路径字符串，比如 "/usr/lib/python3.9:/usr/lib/python3.9/lib-dynload"
Windows 下注意路径分隔符要用 ;，且需确保 python39.dll 所在目录已加入系统 PATH，否则加载失败不报错，只静默失败

怎么让嵌入的 Python 找到你写的 .py 脚本

即使标准库能加载，import mymodule 仍可能失败——因为 Python 的 sys.path 默认不含你的项目目录。不能依赖当前工作目录，C++ 主程序的 cwd 和 Python 的模块搜索路径是两回事。

最可靠的方式是在 C++ 中动态修改 sys.path：

PyRun_SimpleString("import sys");
PyRun_SimpleString("sys.path.insert(0, '/path/to/your/scripts')");

注意：PyRun_SimpleString() 是同步执行，没有返回值检查；若脚本路径含中文或空格，需用原始字符串或双反斜杠（Windows）转义，否则 Python 解析报错。

避免硬编码路径，可用 C++ 获取可执行文件所在目录（如 argv[0] + dirname()），再拼出相对路径
如果要 import 编译后的 .so（Linux）或 .pyd（Windows）扩展模块，确保其依赖的 Python ABI 版本与嵌入的 libpython 严格一致（如 python3.9 不能 load python3.10 编译的模块）
不要在 Py_Initialize() 前调用任何 Python C API 函数，否则崩溃无提示

多线程环境下必须处理 GIL

如果你的 C++ 程序本身是多线程的，又在非主线程里调用 Python API（比如 worker thread 执行脚本），不手动管理 GIL 会导致段错误或数据竞争。Python 解释器不是线程安全的，默认只允许一个线程执行 Python 字节码。

典型场景：主线程初始化解释器，子线程想运行一段 Python 逻辑。必须显式获取 GIL：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

PyThreadState* main_state = PyThreadState_Get();
PyThreadState* new_state = PyThreadState_New(main_state->interp);
PyThreadState_Swap(new_state);
// 此时可以安全调用 PyRun_SimpleString 等
PyThreadState_Swap(nullptr);
PyThreadState_Delete(new_state);

更常见也更轻量的做法是：在需要调用 Python 的线程入口处加锁释放 GIL：

进入 Python 调用前：用 PyGILState_Ensure() 获取 GIL（自动创建线程状态如果不存在）
退出前：用 PyGILState_Release() 归还
这两个函数成对出现即可，无需关心线程状态指针，比手动管理 PyThreadState 更安全
切记：C++ 回调函数被 Python 调用（如通过 PyCFunction 注册）时，GIL 已持有，此时再 Ensure 会死锁

如何安全地从 Python 异常中恢复

嵌入时最易被忽略的细节：Python 抛异常不会自动终止 C++ 程序，但会留在解释器状态里。如果不清除，下一次调用 Python API 可能直接失败，且错误信息还是上一次的。

每次调用可能出错的 Python C API 后（如 PyObject_CallObject、PyImport_ImportModule），必须检查是否出错：

PyObject* result = PyObject_CallObject(func, args);
if (!result) {
    PyErr_Print();  // 打印 traceback 到 stderr
    PyErr_Clear();  // 清除异常状态，否则后续调用全失败
    return;
}

PyErr_Print() 是调试利器，但生产环境建议用 PyErr_Fetch() + PyObject_Str() 捕获错误信息存入日志。

PyErr_Clear() 必须调用，否则异常状态持续存在，哪怕你只是想忽略这个错误
不要在未检查返回值的情况下对 result 调用 Py_DECREF，空指针会导致崩溃
所有从 Python API 返回的 PyObject* 都是 borrowed reference 还是 new reference，必须查文档确认，误用 Py_DECREF 会导致内存泄漏或提前释放

嵌入 Python 解释器不是“胶水层”，它是一条双向通道：C++ 控制生命周期，Python 控制语义逻辑。路径、线程、异常这三关过不去，其余都白搭。