Py_Initialize()常失败的根本原因是Python解释器找不到标准库路径和启动配置，需在调用前用Py_SetPythonHome()或Py_SetPath()显式指定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：
立即学习“Python免费学习笔记（深入）”；
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 字节码。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
典型场景：主线程初始化解释器，子线程想运行一段 Python 逻辑。必须显式获取 GIL：
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 控制语义逻辑。路径、线程、异常这三关过不去，其余都白搭。
