简介CMake 3.25 Windows 版是面向 C 开发者与跨平台项目维护者的自动化构建工具安装包适用于需要在 Visual Studio、MinGW 或 Ninja 等环境下配置、生成并管理复杂工程结构的场景对刚接触 CMake 的初学者和需要升级构建链的资深工程师同样适用。压缩包共收录 7090 个文件以 txt、html、rst 文档和 cmake 模块脚本为主另含少量 c、cxx、cpp 源码示例及 exe 可执行文件整体约 36.31MB文档与脚本比例较高便于离线查阅命令手册与模块说明。该版本在兼容性、新增命令选项、性能优化、错误提示与缓存管理等方面均有改进并更新了第三方模块与脚本语言能力。已有 1333 人学习下载读者可借助其中的命令行与 GUI 配置方式快速完成源码路径、构建目录与编译器选项设置减少大型项目构建耗时提升跨平台编译的稳定性与排错效率。1. CMake 3.25 Windows 版本为什么老项目升级后反而编不过你可能遇到过这种场景接手一个 C 项目CMakeLists.txt里写着cmake_minimum_required(VERSION 3.25)本机装的却是 3.20配置阶段直接报版本不满足或者反过来装了最新的 CMake 3.25结果一个跑了三年的老工程在find_package阶段翻车报出一堆target_link_libraries找不到目标。CMake 3.25 在 Windows 上不是一个「装上就能用」的版本它把SYSTEM属性、block()作用域、FetchContent的SYSTEM支持、以及find_package的SYSTEM传播行为都做了调整这些改动对老项目是实打实的破坏性变更。这篇内容面向在 Windows 上做 C 开发、需要把 CMake 升到 3.25 或在新机器上装 3.25 的人。我会把「装哪个包、装完怎么验证、老项目为什么炸、参数怎么调、坑在哪」按顺序讲清楚。读完你应该能在一台干净的 Windows 机器上把 3.25 跑起来并且知道遇到CMakeDetermineCompilerId.cmake报错、Qt 的Qt5Config.cmake找不到、Ninja 生成器选错这类问题时该看哪里。适合刚接触 CMake 的新手照着做也适合被老项目升级折磨过的熟手对照排查。2. Windows 上装 CMake 3.25三种装法与验证命令2.1 先想清楚装哪种安装包、压缩包还是包管理器Windows 上装 CMake 3.25 常见有三条路选哪条取决于你要不要把它塞进 CI、要不要多版本共存。第一条是官方.msi安装包。双击一路下一步勾选「Add CMake to the system PATH」装完cmake --version直接能用。优点是省事缺点是全局只有一个版本想同时留 3.20 和 3.25 就得靠手动改 PATH。第二条是.zip压缩包。解压到D:\tools\cmake-3.25.3-windows-x86_64然后把bin目录加进 PATH。这种方式适合多版本共存你可以放cmake-3.20、cmake-3.25、cmake-3.28三个目录用哪个就把哪个的bin放到 PATH 最前面。CI 里也常用这种因为不用管理员权限。第三条是包管理器。winget install Kitware.CMake或者choco install cmake --version3.25.3。winget 装的是最新稳定版想锁 3.25 得看仓库里有没有对应版本choco 可以指定版本但需要管理员权限。如果你只是本机开发winget 最省心如果要精确锁版本压缩包最可控。提示不要用「下载一个 exe 然后手动复制到 System32」这种野路子。CMake 依赖同目录下的share文件夹里的模块文件只复制 exe 会导致include(CMakeDetermineCompilerId)这类内置模块找不到报出CMake Error at .../CMakeDetermineCompilerId.cmake:9这种看起来像编译器问题的错误实际是安装不完整。2.2 用压缩包在 Windows 上跑通 3.25 的最小步骤下面这套步骤我在多台 Windows 10/11 机器上复现过从零到能配置一个最小工程大约五分钟。# 1. 下载 cmake-3.25.3-windows-x86_64.zip 后解压到固定目录 # 假设解压到 D:\tools\cmake-3.25.3-windows-x86_64 # 2. 把 bin 目录加入当前会话 PATH临时验证用 set PATHD:\tools\cmake-3.25.3-windows-x86_64\bin;%PATH% # 3. 验证版本和安装完整性 cmake --version # 期望输出cmake version 3.25.3 # 4. 验证内置模块能被找到这一步能提前暴露安装不完整 cmake --help-module CMakeDetermineCompilerId | findstr CMakeDetermineCompilerId第 2 步的set PATH只对当前 cmd 窗口生效关掉就没了。要永久生效用「系统属性 → 环境变量 → 用户变量 Path → 新建」把bin目录加进去然后重开终端。第 3 步的cmake --version如果输出的是别的版本说明 PATH 里还有旧的 CMake用where cmake看看到底命中了哪个。第 4 步是关键很多人装完只验证版本号结果一配置工程就报模块找不到--help-module能提前确认share/cmake-3.25/Modules目录是完整的。2.3 装完必须验证的三件事版本、生成器、编译器探测版本号对了不代表能用。Windows 上 CMake 要干活还得能选到生成器、能探测到编译器。# 查看本机可用的生成器列表 cmake --help # 在输出里找 Generators 段确认有 # Visual Studio 17 2022 # Ninja # MinGW Makefiles # 用一个最小工程验证编译器探测 mkdir D:\tmp\cmake-test cd D:\tmp\cmake-test echo cmake_minimum_required(VERSION 3.25) CMakeLists.txt echo project(hello CXX) CMakeLists.txt echo add_executable(hello main.cpp) CMakeLists.txt echo int main(){return 0;} main.cpp cmake -S . -B build -G Visual Studio 17 2022cmake --help里的生成器列表决定了你能用哪种构建后端。如果你装了 Visual Studio 2022 但列表里没有Visual Studio 17 2022通常是 VS 的 C 工作负载没装全。最后那条cmake -S . -B build -G ...是 3.25 推荐的「源目录/构建目录分离」写法-S指源码目录-B指构建目录。如果这一步报CMake Error at CMakeDetermineCompilerId.cmake:9先别怀疑编译器九成是 CMake 安装不完整或者 PATH 里混了旧版本回到 2.2 重新验证。3. CMake 3.25 在 Windows 上的关键参数与生成器选择3.1 生成器怎么选Visual Studio、Ninja 还是 MinGWWindows 上 CMake 的生成器选择直接决定你后面调试和编译的体验。三种常见组合的差异如下。生成器适用场景编译命令注意点Visual Studio 17 2022用 VS 做 IDE 开发、需要 .slncmake --build build --config Release多配置生成器必须带--configNinja命令行快速构建、CIcmake --build build单配置需先有编译器环境MinGW Makefiles用 MinGW-w64 工具链cmake --build build路径不能有空格和中文选 Visual Studio 生成器时cmake --build后面必须跟--config Debug或--config Release否则默认是 Debug。这是新手最常踩的坑之一明明想编 Release结果出来的是 Debug 版性能差一大截还找不到原因。选 Ninja 时CMake 会去 PATH 里找cl.exe或g.exe如果你是在普通 cmd 里而不是「x64 Native Tools Command Prompt for VS 2022」里跑cl.exe找不到配置阶段就会失败。常见做法是先用 VS 自带的开发者命令行或者手动跑vcvars64.bat。3.2 用 -D 传参CMAKE_BUILD_TYPE、CMAKE_INSTALL_PREFIX 与工具链CMake 3.25 在 Windows 上配置工程时几个-D参数几乎每次都要调。cmake -S . -B build -G Ninja ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_INSTALL_PREFIXD:/install/myproj ^ -DCMAKE_C_COMPILERcl.exe ^ -DCMAKE_CXX_COMPILERcl.exeCMAKE_BUILD_TYPE只对单配置生成器Ninja、MinGW Makefiles有效对 Visual Studio 生成器无效——VS 生成器用--config控制。CMAKE_INSTALL_PREFIX在 Windows 上建议用正斜杠或者双反斜杠单反斜杠会被当成转义字符。CMAKE_C_COMPILER和CMAKE_CXX_COMPILER显式指定编译器能避免 CMake 探测到错误的编译器。如果你用 Ninja 但没指定编译器CMake 可能探测到 MinGW 的 gcc而你其实想用 MSVC后面链接阶段就会出现 ABI 不兼容的诡异错误。注意CMAKE_BUILD_TYPE在 Visual Studio 生成器下被忽略是设计行为不是 bug。如果你在 VS 生成器下设了-DCMAKE_BUILD_TYPERelease却发现还是 Debug别去翻 CMake 源码直接用--config Release。3.3 用 CMakePresets.json 把参数固化下来CMake 3.25 对CMakePresets.json的支持已经很成熟把上面那些参数写进 preset团队里每个人跑cmake --preset windows-release就行不用记一长串-D。{ version: 5, configurePresets: [ { name: windows-release, generator: Ninja, binaryDir: ${sourceDir}/build/release, cacheVariables: { CMAKE_BUILD_TYPE: Release, CMAKE_INSTALL_PREFIX: D:/install/myproj, CMAKE_C_COMPILER: cl.exe, CMAKE_CXX_COMPILER: cl.exe } } ], buildPresets: [ { name: windows-release, configurePreset: windows-release } ] }version: 5对应 CMake 3.25 支持的 presets schema 版本写高了低版本 CMake 读不了。binaryDir用${sourceDir}变量避免硬编码绝对路径。cacheVariables里的键就是-D后面的名字。配好之后配置用cmake --preset windows-release构建用cmake --build --preset windows-release。这套写法在 CI 里特别省事Windows 和 Linux 可以共用一套 preset 结构只改 generator 和 compiler。4. 老项目升级到 3.25 的避坑与排查4.1 现象find_package 找到的库突然变成 SYSTEM 包含现象项目从 CMake 3.20 升到 3.25 后某个第三方库的头文件警告全部消失但你自己代码里同名宏定义开始冲突编译报重复定义。原因CMake 3.25 调整了find_package导入目标的SYSTEM属性传播行为通过find_package引入的 imported target 默认被当作系统包含目录编译器不再对它们报警告同时-isystem和-I的搜索顺序差异可能让头文件解析结果变化。解决如果依赖这个行为在target_link_libraries后显式用set_target_properties关掉或者用target_include_directories手动控制包含路径。更稳妥的做法是升级前先跑一遍cmake --warn-uninitialized和编译警告把依赖的头文件冲突提前暴露。4.2 现象Qt5Config.cmake 在 3.25 下报找不到 Qt5现象配置阶段报CMake Error at C:/Qt/Qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5/Qt5Config.cmake说找不到某个组件或者版本不匹配。原因Qt 5.9 自带的 CMake 配置文件是按老版本 CMake 写的3.25 对find_package的组件检查和版本比较更严格老配置文件里的find_dependency写法可能触发新的校验逻辑。解决在find_package(Qt5 ...)之前设置set(CMAKE_FIND_PACKAGE_PREFER_CONFIG ON)或者把 Qt 升级到 5.15 以上。如果必须用 Qt 5.9可以在顶层CMakeLists.txt里临时降级策略cmake_policy(SET CMP0074 OLD)之类但要逐个确认策略影响。血泪经验是Qt 5.9 CMake 3.25 这个组合本身就不推荐能升 Qt 就升。4.3 现象Ninja 生成器下编译报 cl.exe 找不到现象cmake -G Ninja配置成功但cmake --build build时报cl.exe不是内部或外部命令。原因Ninja 是单配置生成器构建时直接调用编译器而cl.exe只在 Visual Studio 开发者命令行里才在 PATH 中。普通 cmd 或 PowerShell 里没有。解决在「x64 Native Tools Command Prompt for VS 2022」里跑 CMake或者先执行C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat。也可以改用 Visual Studio 生成器它自己知道编译器在哪。4.4 现象CMakeDetermineCompilerId.cmake:9 报错现象配置阶段直接停在CMakeDetermineCompilerId.cmake:9提示编译器 ID 探测失败。原因这个文件是 CMake 探测编译器身份的核心模块报错通常不是编译器本身的问题而是 CMake 安装不完整缺share目录、PATH 里混了多个 CMake 版本、或者临时目录权限不足导致探测程序无法编译运行。解决先where cmake确认只有一个 CMake再cmake --help-module CMakeDetermineCompilerId确认模块存在然后检查%TEMP%目录是否可写。如果都不行换压缩包重新解压一份干净的 3.25别在旧安装上打补丁。4.5 现象路径里有中文或空格导致配置失败现象工程放在D:\我的项目\demo下CMake 配置时报找不到文件或生成器失败。原因Windows 上部分生成器尤其是 MinGW Makefiles和底层工具链对中文路径、空格路径支持不好CMake 传给编译器的路径没有正确加引号时就会断。解决工程路径只用英文和数字不要有空格。如果必须用带空格的路径确保所有-D参数里的路径用引号包起来并且优先选 Ninja 或 Visual Studio 生成器它们对空格路径的容忍度比 MinGW Makefiles 高。5. 用 CMake 3.25 的 block() 和 FetchContent 收尾一个可复现技巧CMake 3.25 引入的block()命令是我在这个版本里最愿意推荐给别人的东西。它把变量作用域限制在一个块里块结束自动恢复不用再手动set回去。配合FetchContent的SYSTEM参数可以在 Windows 上干净地拉取第三方依赖而不污染主工程的包含路径。cmake_minimum_required(VERSION 3.25) project(demo LANGUAGES CXX) include(FetchContent) block(SCOPE_FOR VARIABLES) set(FETCHCONTENT_QUIET OFF) FetchContent_Declare( fmt GIT_REPOSITORY https://github.com/fmtlib/fmt.git GIT_TAG 10.1.1 SYSTEM ) FetchContent_MakeAvailable(fmt) endblock() add_executable(demo main.cpp) target_link_libraries(demo PRIVATE fmt::fmt)block(SCOPE_FOR VARIABLES)让块内的set不影响外面FetchContent_Declare里的SYSTEM让 fmt 的头文件以系统包含方式引入编译器不会对 fmt 内部代码报警告。endblock()之后FETCHCONTENT_QUIET这些变量自动恢复。这个写法在 Windows 上尤其有用因为 MSVC 的警告等级一高第三方库的警告能刷满整个输出窗口用SYSTEM屏蔽掉能让你专注在自己的代码上。验证方法很简单配置一次看build/_deps/fmt-src是否被拉下来再故意在main.cpp里写一个会触发警告的代码确认警告只来自你自己的文件不来自 fmt。如果 fmt 的警告还在检查FetchContent_Declare的SYSTEM是不是写在正确位置——它必须和GIT_REPOSITORY同级。我自己的习惯是新工程一律cmake_minimum_required(VERSION 3.25)起步用block()管依赖用CMakePresets.json管参数Windows 上优先 Ninja vcvars64。老工程升级前先在一个分支上跑一遍完整构建把find_package相关的警告全打开确认没有依赖被意外当成 SYSTEM 再合并。这套流程帮我省过好几次「升完 CMake 编不过又回滚」的来回。希望帮到你。本文还有配套的精品资源点击获取
