Pybind11封装C++类生成.pyd文件后自定义类未暴露问题排查

背景 #

我正在用Pybind11封装基于Qt6构建的动态库中的C++类Package，使其可在Python中调用。编写了包装类PackageExt并绑定到Python模块ContainerPy，相关代码如下：

C++包装头文件（packageext.h） #

#ifndef PACKAGEEXT_H
#define PACKAGEEXT_H

#include "package.h" // 来自动态库

class PackageExt {
public:
    PackageExt(const std::string &id);
    PackageExt(const ContainerCore::Package &pkg);
    PackageExt(const PackageExt &other);
    PackageExt& operator=(const PackageExt &other);
    ~PackageExt();
    void setPackageID(const std::string &id);
    std::string packageID() const;
    ContainerCore::Package* getBasePackage();
private:
    ContainerCore::Package *mPackage; // 定义在动态库中
};

#endif // PACKAGEEXT_H

Pybind11绑定代码（bindcontainer.cpp） #

#include <pybind11/pybind11.h>
#include <pybind11/stl.h>
#include "packageext.h"

namespace py = pybind11;

PYBIND11_MODULE(ContainerPy, m) {
    m.doc() = "Pybind11 plugin for Container library";

    py::class_<PackageExt>(m, "Package")
        .def(py::init<const std::string &>(), py::arg("id"),
             "Constructor that initializes a Package with the specified ID.")
        .def("get_package_id", &PackageExt::packageID,
             "Get the package ID as std::string.")
        .def("set_package_id", &PackageExt::setPackageID, py::arg("id"),
             "Set the package ID using std::string.");
}

CMake配置（CMakeLists.txt） #

find_package(Python REQUIRED COMPONENTS Interpreter Development)
find_package(QT NAMES Qt6 REQUIRED COMPONENTS Core Concurrent Xml Network Sql)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Concurrent Xml Network Sql)
find_package(pybind11 REQUIRED CONFIG HINTS ${PYBIND11_HINTS_PATH})
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
set(BINDING_FILES
    bindcontainer.cpp
    containerext.cpp
    packageext.cpp
    containermapext.cpp
)
pybind11_add_module(${PYTHON_LIB_NAME} MODULE ${BINDING_FILES})
target_link_libraries(${PYTHON_LIB_NAME} PRIVATE Container) # 动态库
target_link_libraries(${PYTHON_LIB_NAME} PRIVATE Qt6::Core Qt6::Concurrent Qt6::Network Qt6::Xml Qt6::Sql)
target_link_libraries(${PYTHON_LIB_NAME} PRIVATE Python::Python)

问题描述 #

构建模块后成功生成.pyd文件，但在Python中导入模块并查看时，输出如下：

import ContainerPy
print(dir(ContainerPy))
# 输出：
['__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__']

Package类及其方法未按预期暴露，需排查问题原因及解决方法。

额外细节 #

• 使用Qt6搭配Pybind11封装C++类
• 动态库链接正常，无构建错误
• 使用CMake构建项目
• 已确认.pyd文件生成，但Python中无法看到类绑定
• .pyd文件路径为ContainerPy/ContainerPy.cpython-313-x86_64-linux-gnu.so，已安装到Python环境的site-packages目录
• 当前在Linux环境构建，代码需支持Windows/macOS

已尝试操作 #

• 确保CMake配置链接了所需的Qt6和Python组件
• 验证所有源文件已包含在BINDING_FILES列表中
• 检查是否存在缺失依赖导致类绑定未显示

疑问 #

1. Pybind11绑定设置是否存在问题？
2. CMake配置或库链接方式有哪些需要检查的点？

排查与解决方法 #

1. 解决模块导入路径冲突 #

你导入的ContainerPy大概率是目录包而非Pybind11生成的.so文件。由于.so文件放在ContainerPy/子目录下，若site-packages中的ContainerPy目录包含__init__.py（哪怕是空文件），Python会优先将其识别为包，而非加载同级的.so模块。

解决方式：

• 删除ContainerPy目录下的__init__.py，或直接将.so文件移至site-packages根目录；
• 若需保留目录结构，在ContainerPy/__init__.py中添加：

  from .ContainerPy import *
  

  导入包时会自动加载内部的.so模块。

2. 验证模块名称匹配 #

确认PYBIND11_MODULE(ContainerPy, m)中的模块名ContainerPy与CMake中${PYTHON_LIB_NAME}变量值完全一致。若变量值不匹配，生成的.so文件名会错位，导致导入错误模块。

检查方式：
在CMakeLists.txt中添加日志输出：

message(STATUS "Python lib name: ${PYTHON_LIB_NAME}")

编译时确认输出名称为ContainerPy。

3. 检查编译符号导出 #

在Linux下执行以下命令，查看.so文件是否包含Pybind11的模块入口符号：

nm -D ContainerPy.cpython-313-x86_64-linux-gnu.so | grep PyInit_

若未找到PyInit_ContainerPy，说明模块入口未正确编译：

• 确认BINDING_FILES列表包含bindcontainer.cpp，且CMake未忽略该文件；
• 强制为模块目标设置位置无关代码：

  set_target_properties(${PYTHON_LIB_NAME} PROPERTIES POSITION_INDEPENDENT_CODE ON)
  

4. 排查Qt6动态库加载问题 #

Qt6的动态库加载顺序可能导致Pybind11模块初始化失败。在Python中导入前开启Qt调试输出：

import os
os.environ["QT_DEBUG_PLUGINS"] = "1"
import ContainerPy

查看输出中的错误信息，确认是否存在Qt库加载失败的情况。

5. 临时排除拷贝构造函数影响 #

PackageExt定义的拷贝构造函数和赋值运算符若存在实现问题（如mPackage浅拷贝导致访问错误），可能导致模块初始化静默失败。暂时注释这两个函数，重新编译测试，看是否能正常暴露类。

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