使用 pybind11 为大型 C++ 项目生成多文件 Python 绑定时，必须仅在一个源文件中调用 PYBIND11_MODULE 宏；其余绑定逻辑应封装为接受 pybind11::module& 参数的初始化函数，并在主模块中统一调用，否则将触发“multiple definition of PyInit_…”链接错误。
使用 pybind11 为大型 c++ 项目生成多文件 python 绑定时，必须仅在一个源文件中调用 `pybind11_module` 宏；其余绑定逻辑应封装为接受 `pybind11::module&` 参数的初始化函数，并在主模块中统一调用，否则将触发“multiple definition of pyinit_…”链接错误。
在实际工程中（如协议栈、序列化库或 ROS 风格的消息系统），常需为数十个 C++ 头文件（如 message_1.h, message_2.h）自动生成对应的 Python 绑定代码（如 message1_bind.cpp, message2_bind.cpp）。若每个 _bind.cpp 文件都直接使用 PYBIND11_MODULE(protocol_name, m)，编译器会为每个文件生成同名的 C API 初始化函数 PyInit_protocol_name，导致链接阶段报错：
ld: error: multiple definition of 'PyInit_protocol_name'
根本原因：PYBIND11_MODULE 是一个宏，底层展开为 extern "C" PyObject* PyInit_<name>(void)</name> 函数定义 —— 而 C/C++ 中同一翻译单元外不可重复定义同名全局函数。
✅ 正确做法是采用 单入口 + 多委托 模式：
- ✅ 唯一主绑定文件（如
main_bind.cpp）中定义PYBIND11_MODULE(protocol_name, m)； - ✅ 其余
_bind.cpp文件不包含PYBIND11_MODULE，而是导出void init_xxx(pybind11::module& m)函数； - ✅ 主文件通过
#include或显式链接引入这些初始化函数，并在模块作用域内逐个调用。
示例结构如下：
messages/message_1.h：
namespace protocol_name {
struct Message1 { int id; std::string data; };
std::string serialize_message_1(const Message1&);
Message1 deserialize_message_1(const std::string&);
}bindings/message1_bind.cpp：
#include <pybind11/pybind11.h>
#include "messages/message_1.h"
void init_message1(pybind11::module_ &m) { // 推荐使用 module_（pybind11 v2.10+）
pybind11::class_<protocol_name::Message1>(m, "Message1")
.def(pybind11::init<>())
.def_readwrite("id", &protocol_name::Message1::id)
.def_readwrite("data", &protocol_name::Message1::data);
m.def("serialize_message1", &protocol_name::serialize_message_1);
m.def("deserialize_message1", &protocol_name::deserialize_message_1);
}bindings/main_bind.cpp：
#include <pybind11/pybind11.h>
// 显式包含各绑定实现（或通过头文件声明 + 链接对象文件）
#include "message1_bind.cpp"
#include "message2_bind.cpp" // 同理
PYBIND11_MODULE(protocol_name, m) {
m.doc() = "Protocol binding for message serialization";
init_message1(m);
// init_message2(m);
// init_service1(m);
}⚠️ 注意事项：
- 不要
#include.cpp文件到构建系统之外的上下文（如头文件中），仅限于主绑定文件内可控包含； - 若使用 CMake，确保所有
_bind.cpp文件均参与编译，但仅main_bind.cpp导出 Python 模块符号； - 推荐升级至 pybind11 ≥ v2.10，使用
pybind11::module_替代裸pybind11::module，避免隐式拷贝风险； - 自动生成脚本中，可为每个消息生成独立的
init_xxx()函数，并在主模板中拼接调用列表，实现完全解耦。
最终效果：Python 端仅需一次导入 import protocol_name，即可访问全部类与函数，既满足模块化开发需求，又严格遵守 Python C API 的单初始化函数约束。
