Windows下pybind11编译C++出现collect2.exe错误的原因排查

Windows与Linux编译pybind11的核心差异 #

• 库链接要求不同：Linux下编译时，Python库通常会被自动检测或仅需-lpython3.x即可链接；但Windows下必须显式指定要链接的Python导入库（如python311.lib），且链接参数的位置有严格要求。
• 符号修饰规则差异：Windows平台下Python的C API符号带有__imp_前缀，需要正确链接对应的导入库才能解析这些符号，而Linux下符号无此前缀。
• 编译器兼容性：官方Windows Python是用MSVC编译的，MinGW编译的模块可能存在ABI兼容性问题，但多数基础场景下可通过正确链接解决。
• 输出文件后缀：Linux生成.so，Windows需要生成.pyd（你已正确设置）。

直接解决方法：修正手动编译命令 #

你的编译命令已指定库路径-L %PYTHON_LIBS%，但缺少链接Python库的具体指令，导致链接器无法找到Python API的实现。修改后的命令如下：

set HASHMAP_INCLUDE=C:\path\to\other\headers\include
set PYBIND11_INCLUDE=C:\path\to\pybind11_x64-windows\include
set PYTHON_INCLUDE=C:\path\to\Python311\include
set PYTHON_LIBS=C:\path\to\Python\Python311\libs
g++ -O3 -Wall -shared -std=c++11 -I %HASHMAP_INCLUDE% -I %PYBIND11_INCLUDE% -I %PYTHON_INCLUDE% -L %PYTHON_LIBS% test.cpp -lpython311 -o test.cp311-win_amd64.pyd

关键改动：

• 添加-lpython311参数，指定链接Python 3.11的导入库
• -lpython311必须放在源文件test.cpp之后，因为g++的链接顺序是从左到右，依赖库需要在被依赖的源文件之后

若仍报错，检查以下内容：

• 确认%PYTHON_LIBS%路径下存在python311.lib文件（官方Python安装包自带）
• 若使用MinGW编译的Python，库文件名可能是libpython311.a，此时仍可使用-lpython311（g++会自动添加lib前缀和.a后缀）

更可靠的方案：使用CMake管理编译 #

手动编写编译命令容易出错，推荐用CMake自动处理平台差异，以下是示例CMakeLists.txt：

cmake_minimum_required(VERSION 3.15)
project(test_pybind)

set(CMAKE_CXX_STANDARD 11)

# 找到Python环境
find_package(Python3 3.11 REQUIRED COMPONENTS Development)

# 添加pybind11
add_subdirectory(path/to/pybind11)

# 生成扩展模块
pybind11_add_module(test test.cpp)

# 链接Python库
target_link_libraries(test PRIVATE Python3::Python)

# 添加其他依赖头文件
target_include_directories(test PRIVATE C:/path/to/other/headers/include)

使用步骤：

1. 在项目目录创建build文件夹，进入后执行：

cmake .. -G "MinGW Makefiles"
mingw32-make

这种方式会自动处理Windows下的库链接、路径配置等问题，避免手动命令的遗漏。

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