CMake调用FindPython3.cmake配置时报列表索引越界错误如何修复

问题场景 #

使用CMake查找Python3依赖时，项目内CMakeLists.txt配置如下：

find_package(Python3 COMPONENTS Interpreter Development REQUIRED)
include_directories(${Python3_INCLUDE_DIRS})
link_libraries(${Python3_LIBRARIES})

执行CMake配置流程后抛出错误：

CMake Error at D:/Program Files/CMake/share/cmake-3.22/Modules/FindPython/Support.cmake:1832 (list):
  list index: 10 out of range (-10, 9)
Call Stack (most recent call first):
  D:/Program Files/CMake/share/cmake-3.22/Modules/FindPython3.cmake:490 (include)
  CMakeLists.txt:2 (find_package)

当前运行环境：

win 10
vs2022 x64
Python 3.7.0
Anaconda

排查发现CMake缓存的Python3解释器内部属性取值为：

_Python3_INTERPRETER_PROPERTIES:INTERNAL=Python;3;10;5;64;;cp310-win_amd64;D:\Python-3.10.5\Lib;D:\Python-3.10.5\Lib;D:\Python-3.10.5\Lib\site-packages;D:\Python-3.10.5\Lib\site-packages

根因分析 #

该错误是多Python版本共存场景下的CMake缓存脏数据导致：

• 本地同时存在Python 3.7.0、Anaconda内置Python、Python 3.10.5三个版本，CMake自动查找时存在版本匹配混乱问题
• 历史CMake配置缓存了Python 3.10.5的解释器属性，但当前环境下该路径不可用/被优先级更高的其他Python版本覆盖
• CMake 3.22版本的FindPython模块对缓存字段长度校验存在缺陷，读取到长度不匹配的缓存属性时，直接访问不存在的索引位触发越界

修复步骤 #

• 彻底清理CMake缓存：删除项目构建目录下的CMakeCache.txt文件，以及整个CMakeFiles文件夹，完全清除历史配置残留，不要在原有缓存基础上重新配置。
• 显式指定目标Python路径：配置CMake时通过参数明确指定要使用的Python解释器绝对路径，跳过自动查找逻辑，避免版本错配。命令行配置示例：

  # 替换路径为你实际要使用的python.exe完整路径，比如Anaconda下的Python3.7路径
  cmake .. -DPython3_EXECUTABLE="C:\你的Python安装目录\python.exe"
  

  如果使用VS2022内置的CMake图形配置界面，直接在CMake配置变量中新增Python3_EXECUTABLE条目，取值为目标python.exe的绝对路径即可。
• 调整环境变量优先级（可选）：将你需要使用的Python版本的安装路径、对应Scripts目录路径，放到系统环境变量PATH中其他Python路径的最前面，避免CMake自动查找时拉取到无效的历史版本路径。
• 升级CMake版本（可选）：如果上述操作后仍偶发报错，可以将CMake升级到3.24及以上版本，新版本修复了多Python版本切换时缓存字段不匹配导致的索引越界问题。

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