pybind11嵌入多版本Python时CMake无法找到正确版本

问题根因 #

pybind11自带的FindPythonLibsNew.cmake模块查找逻辑优先级高于单独传入的版本号参数，Windows环境下会优先读取注册表中登记的Python安装项。本机安装的Python3.9因为注册表登记优先级最高，无论怎么修改pybind11_DIR路径、传入PYBIND11_PYTHON_VERSION参数都会被优先锁定。重命名3.9安装目录后，高优先级路径查找失效，又没有拿到明确的低版本路径指引，就会直接抛出配置错误。

可复现的有效配置步骤 #

• 第一步：彻底清理历史CMake缓存，删除构建目录下的CMakeCache.txt文件和CMakeFiles文件夹。之前扫描到的Python路径会持久化存在缓存中，不清缓存修改任何参数都不会生效。
• 第二步：配置CMake时显式传入Python3.7的全路径参数，不要仅传版本号，参考如下命令（将路径替换为你本机Python3.7的实际安装路径）：

cmake -S . -B build ^
  -Dpybind11_DIR="C:/你的Python3.7安装目录/Lib/site-packages/pybind11/share/cmake/pybind11" ^
  -DPython3_EXECUTABLE="C:/你的Python3.7安装目录/python.exe" ^
  -DPython3_INCLUDE_DIR="C:/你的Python3.7安装目录/include" ^
  -DPython3_LIBRARY="C:/你的Python3.7安装目录/libs/python37.lib" ^
  -DPYBIND11_PYTHON_VERSION=3.7

注意：Windows下写路径统一用正斜杠，不要用单个反斜杠，避免CMake转义失败识别路径错误。如果用CMake GUI配置，直接在参数列表手动添加上述三个Python3_开头的路径参数，填写正确后再点击Configure。

• 第三步：配置完成后先做校验，打开构建目录下的CMakeCache.txt，搜索Python3_EXECUTABLE、Python3_LIBRARY条目，确认路径全部指向Python3.7安装目录后，再执行编译构建。

避坑说明 #

• 不要同时设置无版本后缀的Python_EXECUTABLE和带版本后缀的Python3_EXECUTABLE参数，新版pybind11优先识别带版本后缀的参数，混设会触发版本拾取冲突。
• 如果系统全局配置过PYTHONHOME、PYTHONPATH环境变量指向3.9版本，配置和运行阶段临时清空这两个变量，避免编译或运行时加载错版本的依赖。
• 编译完成后将Python3.7目录下的python37.dll复制到生成的可执行文件同目录，避免运行时搜索dll时优先加载到其他版本的Python库。
• 如果用Visual Studio内置的CMake开发环境，不要依赖IDE自动扫描的Python环境，直接在CMakeSettings.json的variables节点下添加上述三个Python3路径参数，再重新生成CMake缓存。

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