简介：面向 Windows 平台 C++ 开发者的 CMake 3.25 安装包与文档集合，适合在 Visual Studio、MinGW 或 Ninja 环境下管理项目构建、生成工程文件并排查配置问题。压缩包共 7090 个文件，约 36.31MB，以 txt、html、rst 说明文档和 cmake 模块脚本为主，另含 exe 安装程序与少量示例源码，安装后可随时查阅。已有 1337 人学习下载。包内提供 cmake、ctest、cpack、cmake-gui 手册，以及命令、属性、变量、策略和模块说明，可用于核对构建参数、理解 CMakeLists 写法、定位生成阶段报错，也能配合命令行与图形界面完成项目配置与构建流程梳理。

1. 装 CMake 3.25 之前，先看清 Windows 上这套工具链的边界

一个 C++ 工程发过来，第一行写着cmake_minimum_required(VERSION 3.25)，我这边敲cmake --version，回的是 3.20 出头——configure 直接停在策略检查那一步，报错信息还只提了一半原因。CMAKE 3.25 windows 版本这类安装包要解决的，就是让 c++ 项目的构建入口有一个确定版本，而不是让三份不同的 CMake 在 PATH 里抢位置：VS 安装器顺带塞的那份、以前为某个老项目装的那份、Python 环境里 pip 装的那份，谁先被找到全看运气。Windows 上的 CMake 从来不是"装上就行"，它是编译器、生成器、SDK 三者的调度台，版本差半代，报错就跑偏到别的地方去。这份 3.25 适合两类人：要吃block()这类新命令的新工程，以及必须把构建版本钉死在某个补丁号上的存量项目。

2. 选包与下载：msi、zip、包管理器三条路的取舍

Windows 上拿 CMake 有三条正经路，选哪条不取决于谁更"现代"，取决于这台机器上有没有管理员权限、要不要多版本并存、以后谁负责升级。3.25 系列的收尾补丁是 3.25.3，装新不装旧，补丁号里修的多半是生成器和 Find 模块的边角问题，工程越大越容易撞上，没必要为了"和同事一致"停在 3.25.0。

2.1 msi 安装包的选项逐项拆解

msi 是绝大多数人的第一选择，双击之后真正需要动脑的只有一页：PATH 选项。三个单选分别是"为所有用户加入系统 PATH""只为当前用户加入 PATH""不加入 PATH"。选第一个，CMake 会写进系统级 PATH，所有账户都能用；选第二个写进用户级 PATH；选第三个就得自己配。机器只有你一个人用，选系统级最省事；如果是多人共用或者公司电脑，选用户级，卸载时不会牵连别人。

安装路径默认落在C:\Program Files\CMake，里面是bin、share、doc三个目录，bin下才是cmake.exe、cmake-gui.exe、ctest.exe、cpack.exe四个可执行文件。想批量铺机器或者写进部署脚本，用静默安装：

# /qn 无界面安装，/norestart 装完不自动重启，ADD_CMAKE_TO_PATH 控制 PATH 写入范围 msiexec /i .\cmake-3.25.3-windows-x86_64.msi /qn /norestart ADD_CMAKE_TO_PATH=System # 装完验证 bin 目录是否落地 Get-ChildItem "C:\Program Files\CMake\bin" | Select-Object Name

ADD_CMAKE_TO_PATH取值是System、User、None三选一，不写这个属性时安装程序会弹交互界面，在 CI 或远程脚本里就等于卡死。/norestart别省，有些环境的 MSI 会带重启标记，把流水线节点重启了很难排查。

卸载走的是标准 MSI 流程，控制面板能找到；找不到就用注册表里的 Uninstall 键按DisplayName匹配 CMake 拿 ProductCode，再msiexec /x {ProductCode} /qn。卸载前先把 PATH 里那条C:\Program Files\CMake\bin记下来，MSI 卸载偶尔会留下空目录和一条失效 PATH 项，下次装新版就会出现两条路径指向不同版本，这就是后面第 5 章那个"两个终端版本不同"的来源。

2.2 zip 便携版和包管理器的适用场景

zip 版是解压即用，不解压到系统目录，不写注册表，不碰 PATH。多版本并存的机器我基本都用它：

# 解压到自定义工具目录，并改成短目录名，方便后面切版本 Expand-Archive -Path .\cmake-3.25.3-windows-x86_64.zip -DestinationPath D:\tools\ Rename-Item D:\tools\cmake-3.25.3-windows-x86_64 cmake-3.25.3 # 直接用绝对路径调，先确认二进制本身没问题 & D:\tools\cmake-3.25.3\bin\cmake.exe --version

第一步的Expand-Archive要留出足够空间，解压后的目录体积比压缩包大不少，放在系统盘临时目录容易半路失败。第二步改名不是洁癖，是因为 CMake 压缩包解出来的目录名带完整版本串，写进脚本里又长又容易抄错，统一改成cmake-<版本>之后，切换版本只要改一行变量。

包管理器适合已经用它管全机器工具的人。winget 的清单不一定收全每个补丁号，先搜再装：

# 先搜，确认清单里有没有 3.25.x 这一档 winget search cmake # 把搜出来的发行版 ID 原样填进 --id，--version 指定到补丁号，-e 精确匹配 winget install --id <搜索结果的 ID> --version 3.25.3 -e

-e是精确匹配 ID，不加这个参数，--id会被当成模糊串去撞名字相近的包，装错东西的概率不低。Chocolatey 的话用choco install cmake --version=3.25.3 --install-arguments="ADD_CMAKE_TO_PATH=System" -y，--install-arguments就是把 msi 那套属性透传下去，行为和手动装 msi 完全一致。Scoop 默认桶里通常只有最新稳定版，要老版本得先加 versions 类的桶，命令写成scoop install cmake@3.25.3的形式，桶没加会直接报找不到。

三种方式的差别集中在这几处：

2.3 安装前先核对：VS 与 SDK 的版本搭配

CMake 本身只是调度台，真正编译的是 MSVC。3.25 里 VS 生成器的名字和本机 Visual Studio 大版本是死绑的：VS2019 对应Visual Studio 16 2019，VS2022 对应Visual Studio 17 2022。本机只装了 VS2019，却写 17 2022，configure 会直接告诉你找不到生成器；反过来用 16 2019 但机器上只有 2022，同样失败。

核对手段有两个，第一个是让 CMake 自己列：

# 输出里找 Generators 段落，这一段只列本机能用的生成器 cmake --help

第二个是问 VS 安装器。安装器目录下自带一个vswhere.exe，把它所在目录临时加进 PATH 或者用全路径调用：

# 列出本机所有装了 C++ 编译工具集的 VS 实例路径 vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath

-requires后面那个组件 ID 是 MSVC 的 C++ 生成工具集，没装这个组件的 VS 实例会返回空——也就是说你机器上虽然有 VS，但只装了 .NET 或者 UWP 工作负载，CMake 一样调不动编译器。这一步是很多"生成器找不到"问题的真正原因，跟 CMake 版本没关系。

Windows SDK 版本也要顺便看一眼，10.0.19041和10.0.22621在同一个工程里混用会导致链接阶段报符号缺失。3.25 的 VS 生成器默认取本机最新的 SDK，要在工程里固定，就在 configure 时传-DCMAKE_SYSTEM_VERSION=10.0.19041.0，这个变量只对 Windows 目标生效，别写到跨平台的公共配置里。

3. 装完第一件事：PATH、环境变量与多版本共存

装完能敲出版本号只是及格线，真正决定后面顺不顺的是"哪一份 cmake 被找到"。Windows 上的路径解析不像 Linux 那样有明确的哈希刷新机制，改完环境变量，已经开着的终端是不会更新的，这个坑我踩过不止一次，血泪经验就是改完 PATH 先关掉所有终端窗口再开。

3.1 PATH 的优先级到底怎么排

Windows 进程的 PATH 是拼出来的：系统级 PATH 在前，用户级 PATH 追加在后。所以如果 msi 选了"所有用户"，那条C:\Program Files\CMake\bin就会排在用户 PATH 里任何一条之前——包括你用 zip 版手动加进去的那条。这就是"明明我把新版本路径放前面了，怎么还是旧的"的根源。

排查用两条命令，第一条看最终命中的是哪个：

# 看实际被调用的 cmake 路径和版本 Get-Command cmake | Select-Object Source, Version where.exe cmake

where.exe会把 PATH 里所有叫cmake.exe的条目按顺序列出来，第一行就是生效的那个。第二条命令看 PATH 的实际拼接结果：

# 按分号拆开逐条打印，位置越靠前优先级越高 $env:PATH -split ';' | Where-Object { $_ -like '*cmake*' }

看到两条以上指向不同目录，就该做减法了。我一般只留一条生效路径，其余版本全部从 PATH 里摘掉，改用绝对路径调用——多一条可疑路径，将来就多一次"为什么这台机器和那台机器编出来不一样"的会议。

提示：用setx改环境变量要小心，它对超过 1024 字符的值有截断风险，PATH 长的机器上可能把后半段直接吃掉。稳妥做法是在系统属性对话框里改，或者用 PowerShell 的[Environment]::SetEnvironmentVariable。

3.2 我常用的多版本切换办法

要在 3.25 和别的版本之间来回切，最省心的不是改系统 PATH，而是每个项目配一个入口脚本。在项目根目录放一个env.bat：

@echo off REM 把 3.25.3 的 bin 目录前置，覆盖系统里可能存在的其他版本 set "CMAKE_HOME=D:\tools\cmake-3.25.3" set "PATH=%CMAKE_HOME%\bin;%PATH%" REM 打印一次版本，确认切换生效 cmake --version REM 保留一个子 shell，退出这个窗口不影响外部环境 cmd /k

set "PATH=...;%PATH%"这种写法把新目录顶到最前面，进程级生效，不影响系统设置，窗口一关就还原。cmd /k是让子 shell 保持打开，否则脚本执行完窗口立刻消失，看不出效果。这套做法在需要同时维护多个老项目的机器上特别管用，缺点是每个项目都要点一次，所以我通常把它挂在编辑器的工作区启动脚本里。

编辑器那一侧也要对一下。VS Code 的 CMake Tools 扩展有自己的cmake.cmakePath配置项，默认是cmake，也就是走 PATH。如果你在 env.bat 里切了版本，但编辑器是从任务栏直接启动的（继承的是系统环境），两边版本就会不一致——终端里 3.25.3，编辑器里还是老的。要么把cmake.cmakePath写死成绝对路径，要么固定从配好环境的终端里启动编辑器。

Visual Studio 内部那套 CMake 集成又是另一回事，它自带一份，并且在项目属性里可以单独指定可执行文件路径。用 VS 打开 CMake 工程时如果版本不对，去工程的 CMake 设置里把路径指到 3.25.3 的bin\cmake.exe，别去改系统 PATH，改了对它没用。

3.3 CMake 自己认的几个环境变量

除了 PATH，CMake 还会读一批同名环境变量作为缓存变量的初始值。这些变量在 configure 时如果命令行没显式传-D，就会拿环境变量顶上——用好了能少敲一长串参数，用不好就是玄学报错。

设置方式和普通环境变量一样，用户级用：

# 用户级持久化，新开的终端生效；当前会话要立刻生效就再手动赋一次 $env:CMAKE_GENERATOR [Environment]::SetEnvironmentVariable('CMAKE_GENERATOR', 'Ninja', 'User')

这里有个取舍要说清楚：CMAKE_BUILD_TYPE设成全局环境变量，对单配置生成器（Ninja、MinGW Makefiles）很方便，但对多配置生成器（Visual Studio 系列）完全无效，因为后者在 build 阶段用--config决定。我见过有人把CMAKE_BUILD_TYPE=Debug写进系统环境变量，结果所有 Ninja 工程默认成了 Debug，性能测试数据全废。这类变量我更倾向写在项目的 CMakePresets.json 里，不写进系统环境，跟着仓库走才不会互相污染。

CMAKE_PREFIX_PATH是唯一值得放系统级的，因为依赖库的安装位置通常和项目无关。多个路径之间用分号分隔，Windows 上别用冒号——冒号在盘符里已经占了。

4. 配置生成器与工具链：让 3.25 认对你的编译器

生成器选错，是 Windows 上 CMake 翻车率最高的一环，而且症状特别有迷惑性：报错看着像代码问题，实际是构建系统没配对。3.25 支持的 Windows 生成器主要就三族——Visual Studio 系列、Ninja、MinGW/NMake Makefiles，选哪族取决于你的依赖库是用什么工具链编的。

4.1 生成器怎么选

VS 生成器是"多配置"的，一次 configure 出 Debug 和 Release 两套，build 时用--config选：

# -S 指定源码目录，-B 指定构建目录，-A x64 指定目标平台 cmake -S . -B build -G "Visual Studio 17 2022" -A x64 # 构建时选配置，Debug 换成 Release 不需要重新 configure cmake --build build --config Release --parallel

-A x64不能省。3.25 的 VS 生成器默认架构跟安装的 VS 组件有关，有的机器上会落到 Win32，产出的 exe 是 32 位的，链接 64 位依赖库时全部报符号不匹配。-T host=x64是另一个维度，它控制的是编译过程本身用 64 位工具链，工程大、头文件多的时候能避免编译器内存不够，和-A不冲突，可以一起用。

Ninja 是"单配置"的，速度快，但要求cl.exe已经在 PATH 里，也就是必须在开发者命令提示符里执行：

# 单配置生成器必须显式给构建类型，否则默认是空，编译选项里没有优化 cmake -S . -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Release # Ninja 下不需要 --config，直接构建 cmake --build build-ninja

这一步最容易出的错是"在普通 PowerShell 里跑 Ninja"，报错是CMAKE_CXX_COMPILER not set或者干脆找不到cl。解决办法不是硬指定编译器路径，而是从开始菜单里找那个带 x64 字样的开发者命令提示符，环境变量都是它初始化好的。实在要在普通终端里跑，就在 configure 时传-DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl，但这条路依赖 VS 环境变量已经存在，本质还是绕不开初始化脚本。

MinGW 和 NMake 现在用得少了，除非依赖库本身就是 MinGW 编的。混用工具链是另一个经典坑：用 MSVC 编的主程序去链 MinGW 编的库，.lib和.a对不上，链接器报出来一堆看不懂的undefined symbol。判断方法很简单，看依赖库目录里是.lib还是.a，和生成器对齐就行。

4.2 CMakePresets.json 把参数固定下来

命令行参数敲多了必然抄错，3.25 对 presets 的支持已经很完整，把生成器、架构、构建类型、缓存变量全写进文件，团队里谁 clone 下来都是同一套：

{ "version": 6, "configurePresets": [ { "name": "vs2022-x64", "displayName": "VS2022 x64", "generator": "Visual Studio 17 2022", "architecture": "x64", "binaryDir": "${sourceDir}/build/vs2022", "cacheVariables": { "CMAKE_CONFIGURATION_TYPES": "Debug;Release" } }, { "name": "ninja-release", "generator": "Ninja", "binaryDir": "${sourceDir}/build/ninja", "cacheVariables": { "CMAKE_BUILD_TYPE": "Release", "CMAKE_CXX_STANDARD": "20" } } ], "buildPresets": [ { "name": "vs2022-release", "configurePreset": "vs2022-x64", "configuration": "Release" } ] }

version字段是最容易踩的一条：6 这一档要求所有人的 CMake 都到 3.25，团队里还有人停在 3.21 就退回 3，否则别人打开就报版本不支持。binaryDir里用${sourceDir}而不是写死路径，避免有人 clone 到不同盘符就失效。architecture在多配置生成器里等价于-A，cacheVariables里的东西等价于-D，一个字段对应一个命令行参数，对照着看就明白。

用起来就两条命令：

# 按预设 configure，等价于那一长串 -G -A -D cmake --preset vs2022-x64 # 按预设 build，configuration 已经在文件里指定 cmake --build --preset vs2022-release

改参数只改 json，不用到处翻脚本。这套东西还有一个隐性好处：新人进来不用问"你们怎么编的"，看文件就行。

4.3 CMakeLists.txt 里 3.25 才有的写法

装 3.25 不全是版本对齐，它确实带来了几个能减少全局变量污染的命令。最实用的是block()/endblock()，做作用域隔离：

cmake_minimum_required(VERSION 3.25) project(demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 20) # block 内部对变量的修改不会泄漏到外部，适合放临时的编译选项 block() set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W4") add_library(inner_lib STATIC src/inner.cpp) endblock() # 这里拿到的 CMAKE_CXX_FLAGS 还是外面那个，没被污染 add_executable(demo src/main.cpp)

block()后面的endblock()是 3.25 才有的，把老版本 CMake 换成 3.25 之后才敢这么写。作用域隔离的好处是子目录里那些"临时改一下编译选项"的代码不再污染全局，以前只能靠function()包一层，写起来啰嗦。

return(PROPAGATE <var>...)也是 3.25 的新增，从函数里往外传值不用再依赖PARENT_SCOPE那种容易写错的作用域参数：

function(find_third_party out_var) set(found_path "D:/libs/third_party") if(EXISTS "${found_path}") # 把结果沿调用栈往上传递，直到有人 set 住它 return(PROPAGATE found_path) endif() endfunction() find_third_party(THIRD_PARTY_DIR) message(STATUS "third party: ${found_path}")

PROPAGATE后面可以跟多个变量名，注意它只对当前作用域链生效，跳出整个目录就断了。

第三个要留意的是版本声明本身。cmake_minimum_required(VERSION 3.25)是硬门槛，低于这个版本的 CMake 直接拒绝配置。团队里版本参差的时候可以用范围写法cmake_minimum_required(VERSION 3.25...3.27)，前者是必须的最低版本，后者是策略上限，处理策略变化时更平滑。另外，3.25 这一代把对过老版本声明的容忍度收紧了，那些还写着cmake_minimum_required(VERSION 3.0)的工程会直接报错，迁移时先批量改声明，别急着改代码。

5. 常见问题排查：装完 cmake 不是找不到就是生成器报错

下面这几条是我在 Windows 上装 3.25 遇到频率最高的，现象、原因、解决按顺序记，遇到对得上的先照做，别急着重装。

现象一：同一个工程，命令提示符里cmake --version是 3.25.3，另一个终端或者编辑器里还是 3.20。原因不是没装对，是环境变量在进程启动时就已经快照了，改完之后开着的终端不会刷新；另一个常见来源是 msi 和 zip 两份并存，系统 PATH 里那条排在前面。解决方法是先关掉所有终端窗口重开，再跑where.exe cmake看有没有多条，多余的那条从 PATH 里删掉；编辑器那边单独检查cmake.cmakePath或者 VS 工程里的 CMake 路径设置。

现象二：Could not create named generator Visual Studio 17 2022。原因通常是本机压根没装 VS2022，或者装了但没勾"使用 C++ 的桌面开发"这个工作负载，vswhere查出来是空。也有可能只是名字抄错，少一个空格或者年份写成 2019。解决方法是先用vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath确认本机有哪些可用实例，再用cmake --help里的 Generators 段落原样复制名字，别手打。

现象三：切到 Ninja 之后报找不到编译器，或者No CMAKE_CXX_COMPILER could be found。原因是在普通终端里跑，cl.exe不在 PATH；也可能CMAKE_MAKE_PROGRAM指着一个不存在的ninja.exe。解决方法是改用带 x64 字样的开发者命令提示符，或者显式传-DCMAKE_MAKE_PROGRAM=<ninja 绝对路径>。判断环境有没有初始化好，敲一句where cl，能出一行就说明对了。

现象四：源码目录带中文或者空格，configure 阶段报文件找不到、编码乱码。原因是部分生成器和工具链对非 ASCII 路径处理不干净，尤其老版本的第三方库脚本。这类问题特别玄学，报错位置和真实原因差着十万八千里。解决方法很土：整个工程路径只用英文、数字、下划线，别带空格，一个字符都别赌。

现象五：老工程升级后报Compatibility with versions of CMake older than 3.5 is now an error。原因是 3.25 收紧了对过老版本声明的兼容策略，以前打警告的地方现在直接报错。解决方法是把cmake_minimum_required里的版本号统一改到 3.5 以上，改完再 configure；这一步不要跳过，因为策略行为变了，后面的构建结果也可能跟着变，早暴露比晚暴露好。

还有一条不算 bug 但很耗时间的：卸载重装之后 PATH 里留了两条C:\Program Files\CMake\bin，看着一样，实际上一条指向已删除目录。where.exe cmake只会显示存在的那条，看不出问题，要直接看 PATH 拆分结果才能发现。我的习惯是每次重装前先把旧的 PATH 项清干净，装完再加，别指望安装程序帮你收拾。

6. 验证跑通：一个最小工程从 configure 到 build 走完

装完不算完，能从头到尾走通一个最小工程才算。我一般用一个刻意做小的工程做验收，带上 3.25 的新语法，只要它能编出来，说明生成器、编译器、SDK、CMake 版本四处都对上了。

工程就两个文件。CMakeLists.txt这么写：

cmake_minimum_required(VERSION 3.25) project(smoke LANGUAGES CXX) # 用 block 隔离一下，顺带验证 3.25 的新命令真的可用 block() set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(smoke main.cpp) endblock() enable_testing() add_test(NAME smoke_runs COMMAND smoke)

main.cpp里打个版本号出来就够：

#include <cstdio> int main() { // 用 __cplusplus 反查编译器实际生效的标准，比看 CMake 变量靠谱 std::printf("cplusplus=%ld\n", static_cast<long>(__cplusplus)); return 0; }

然后按顺序走三步。configure 阶段用 preset 或者命令行都行，这里用命令行更直观：

# 配置，产出 build 目录；失败会在这里停住并打印具体原因 cmake -S . -B build -G "Visual Studio 17 2022" -A x64 # 构建 Release，--parallel 让 MSBuild 自己决定并发 cmake --build build --config Release --parallel # 跑测试，-C 指定配置，--output-on-failure 让失败用例打印日志 ctest --test-dir build -C Release --output-on-failure

三步里任何一步失败，报错信息都会指向具体环节：configure 失败看生成器和编译器，build 失败看头文件和链接，ctest 失败看进程能不能起来。这套流程跑通之后，可以再补一次版本自检，把结果记下来当基线：

# 一次性打印版本、系统信息和默认生成器，存成文本备查 cmake --version cmake --system-information | Select-String -Pattern 'CMAKE_GENERATOR|CMAKE_CXX_COMPILER:|CMAKE_SYSTEM_VERSION'

--system-information输出很长，用Select-String过滤三行就够，分别是生成器、编译器路径和系统版本。这三行对上了，后面的项目基本不会因为环境问题返工。

验收项我整理成这张表，装完机器逐条打勾：

这张表我一般会贴在工位旁边，新机器、重装系统、换笔记本都走一遍，五分钟的事，比事后查"为什么只有我这台编不过"省太多时间。从那以后我每次装 CMake 都强制走一遍这个最小工程，哪怕只是升个补丁号——版本号敲出来对，不代表生成器、编译器、SDK 三方都对得上，跑一次比看十行--version踏实。希望对你有帮助，这份 Windows 侧的 3.25 安装包拿过去，按上面顺序装、配、验一遍，环境就算立住了。

本文还有配套的精品资源，点击获取