使用pybind11嵌入Python的C++应用如何打包内置Python解释器

你提出的「pybind11嵌入Python必须依赖终端用户预装系统Python」的认知不成立。Python原生支持嵌入式部署，无论静态链接单文件、还是随包携带动态运行时的方案都可落地，最终能实现和Lua嵌入一致的体验：用户安装应用后无需提前安装任何Python组件即可运行自定义脚本。

pybind11本身是header-only库，不处理Python链接逻辑，静态链接的核心是直接链接CPython的静态编译产物，配置步骤如下：

• 编译CPython静态库：Windows下编译CPython源码时定义Py_NO_ENABLE_SHARED宏，屏蔽动态库导入逻辑；Linux/macOS下执行CPython源码编译配置时传入--disable-shared --enable-static参数，生成libpython3.x.a静态库文件。
• 应用编译链接：将生成的Python静态库加入C++应用的链接输入项，同时把Python标准库的pyc字节码打包进应用资源段，或放置在应用目录的固定相对路径下，供解释器启动时加载。
• 注意事项：如果需要支持用户脚本加载第三方二进制Python扩展，Linux下编译主程序需加-rdynamic参数导出全局符号，Windows下需在编译时导出Python核心符号表，否则动态加载的扩展会因找不到符号崩溃。

这是生产环境更常用、兼容性更好的方案，不需要依赖系统Python，配置步骤如下：

• 准备运行时包：Windows可直接使用官方提供的嵌入式Python压缩包，Linux/macOS可自行编译生成带相对加载路径的libpython3.x.so/libpython3.x.dylib，将所有运行时文件放在应用安装目录的固定子文件夹下，例如./py_runtime/。
• 配置动态库搜索路径：Windows下可在程序启动最开始调用SetDllDirectory将py_runtime目录加入DLL搜索列表，或直接把Python核心dll放在可执行文件同目录；Linux下编译主程序时设置rpath为$ORIGIN/py_runtime；macOS下通过install_name_tool修改动态库的依赖路径为@executable_path/../py_runtime/下的对应文件，确保程序优先加载随包分发的Python动态库，不会搜索系统路径。
• 配置解释器搜索路径：必须在pybind11解释器初始化（即创建py::scoped_interpreter实例）之前，调用Python C API设置运行时路径，完全屏蔽系统Python的路径干扰，核心代码示例：

#include <pybind11/embed.h>
#include <filesystem>

namespace py = pybind11;

// 注意：实际生产中需通过系统API准确获取可执行文件自身所在目录，不要直接取进程工作目录
std::filesystem::path get_exe_dir();

int main() {
    const std::filesystem::path exe_dir = get_exe_dir();
    const std::filesystem::path py_home = exe_dir / "py_runtime";
    const std::filesystem::path py_lib_path = py_home / "Lib";
    const std::filesystem::path py_site_pkg = py_home / "Lib/site-packages";

    // 以下两个API必须在Py_Initialize执行前调用，否则配置不生效
#if defined(_WIN32)
    Py_SetPythonHome(py_home.wstring().c_str());
    Py_SetPath((py_lib_path.wstring() + L";" + py_site_pkg.wstring()).c_str());
#else
    Py_SetPythonHome(py_home.string().c_str());
    Py_SetPath((py_lib_path.string() + ":" + py_site_pkg.string()).c_str());
#endif

    py::scoped_interpreter guard{};
    // 后续执行用户自定义脚本逻辑即可
    py::exec(R"(
print("Embedded Python running, no system Python required")
)");
    return 0;
}

• 体积优化：可以删除运行时包中不需要的组件，比如内置IDE、文档、测试用例、冗余的标准库模块，最终运行时体积可压缩到15MB左右，和Lua嵌入的体积差距可控。

• 如果你不需要支持用户自行安装二进制第三方Python包，优先选择静态链接方案，最终可输出单个可执行文件，分发体验最优。
• 如果你需要兼容常规Python第三方生态，选择动态链接+随包分发运行时的方案，踩坑成本更低，稳定性更好，只要路径配置正确，完全不会和用户系统上可能安装的其他Python版本产生冲突。

内容的提问来源于stack exchange，提问作者Addy