Windows下VS+CMake+VCPkg构建PyBind11 Debug模式遇LNK1104错误

问题原因分析 #

核心原因是CMake/PyBind11在Debug模式下未正确关联Python的Debug库（python310_d.lib），常见触发场景包括：

• VCPkg安装的Python包未包含Debug库文件；
• CMake的find_package(Python3)未正确识别Debug组件；
• PyBind11的CMake模块在特定版本下强制链接了Release版Python库；
• Visual Studio的CMake缓存残留导致配置未更新。

可行解决方案 #

1. 验证VCPkg安装的Python包是否包含Debug库 #

前往VCPkg安装目录（默认C:\vcpkg\installed\x64-windows），检查lib文件夹下是否存在python310_d.lib：

• 若不存在，需安装带Debug的Python包：

  vcpkg install python3.10:x64-windows --feature-flags=install-debug
  

• 若已存在，继续执行后续步骤。

2. 修正CMakeLists.txt配置，强制Debug模式链接Python Debug库 #

修改项目根目录的CMakeLists.txt，明确指定Debug/Release模式对应的Python依赖：

cmake_minimum_required(VERSION 3.24)
project(your_pybind_project)

find_package(pybind11 REQUIRED)
# 明确要求Python3包含Development组件（含Debug库）
find_package(Python3 3.10 REQUIRED COMPONENTS Development)

pybind11_add_module(your_module src/main.cpp)

# 区分模式链接对应库
if(MSVC AND CMAKE_BUILD_TYPE STREQUAL "Debug")
    target_link_libraries(your_module PRIVATE Python3::Debug)
else()
    target_link_libraries(your_module PRIVATE Python3::Python)
endif()

3. 清理CMake缓存并重新生成项目 #

在Visual Studio中执行操作：

• 右键项目 -> CMake -> 清理缓存；
• 右键项目 -> CMake -> 配置；
• 右键项目 -> CMake -> 生成；
  完成后重新尝试Debug构建。

4. 手动指定Debug库路径（备选方案） #

若上述方法无效，可直接在CMakeLists.txt中硬编码Debug库路径：

if(MSVC AND CMAKE_BUILD_TYPE STREQUAL "Debug")
    # 替换为你的python310_d.lib所在目录
    target_link_directories(your_module PRIVATE "C:/vcpkg/installed/x64-windows/lib")
    target_link_libraries(your_module PRIVATE python310_d.lib)
else()
    target_link_libraries(your_module PRIVATE python310.lib)
endif()

5. 检查VCPkg Triplet配置 #

确保Debug模式下Triplet与安装的Python包匹配：

• 在Visual Studio的CMake设置中，确认VCPKG_TARGET_TRIPLET为x64-windows（而非x64-windows-release）；
• 命令行构建需指定：

  cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -DCMAKE_BUILD_TYPE=Debug
  

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