简介：这份面向Windows平台C++开发者的CMake 3.25工具包，提供跨平台构建系统的安装程序与配套文档，适合需要管理多模块工程、统一Visual Studio与MinGW等编译环境的中初级开发者，可用于缓解项目配置、生成、迁移及团队协作中的兼容性与效率问题，尤其在多种编译器间切换时更具参考价值。压缩包共7090个文件，约36.31MB。内容以txt、html、rst说明与参考手册为主体，辅以cmake模块脚本、in配置模板、json元数据、c/cpp/h源码示例以及少量exe可执行程序，覆盖命令行构建、图形界面配置、测试打包和模块扩展等使用场景，目录层级清晰，便于按用途快速检索和查阅。已有1337人学习下载。包内文档系统整理了命令、属性、变量与策略等主题，并附命令行、图形界面及模块相关手册，可在编写CMakeLists.txt、配置生成目录时核对参数含义、定位配置错误，也可用于了解3.25版本在编译器兼容性、缓存管理和脚本语法方面的改进，适合作为Windows平台C++构建工作的案头参考资料。

1. 版本选型：为什么我建议直接装 CMake 3.25 的 Windows 发行包

有台新机器上，一位开发者用cmake --version查出来是 3.19，接着敲cmake -S . -B build -G "Visual Studio 17 2022"，终端回了一句找不到生成器，整个 C++ 项目连配置阶段都进不去。排查下来是他 IDE 里自带的旧版本抢在 PATH 前面，而不是 CMake 3.25 没装好；普通 C++ 工程在 Windows 上最容易被低估的一步，反而就是“装 CMake”。CMake 3.25 的 Windows 发行包体积不大，命令行参数也不多，真正费时间的都在版本共存、PATH 顺序和生成器选择上。这篇记录按“装什么版本—怎么装—怎么配—坏了怎么救”的顺序走一遍，适合刚接触 cmake c++ 构建、或者要从旧版本迁到 3.25 的人。

2. 装前清点：CMake 3.25 需要的编译器、生成器和目录

CMake 本身不编译任何一行 C++ 代码，它只做一件事：读CMakeLists.txt，然后生成某个构建系统能认的工程文件。所以装 CMake 3.25 之前，得先想清楚两件事：用哪个编译器出二进制，用哪个生成器把编译器串起来。这两件事定不下来，装完的 CMake 多半还是跑不动。

2.1 三种安装形态：MSI、ZIP 免安装与随 IDE 附带的版本

Windows 上的 CMake 3.25 常见三种来源，我按优先级排一下：官方 MSI 安装包、官方 ZIP 压缩包、IDE 附带的版本。MSI 走的是标准安装向导，会写注册表、建开始菜单快捷方式，可以选择把bin目录加进系统 PATH，适合一个人一台机器长期用。ZIP 包解压即用，不写注册表，适合要在 3.24、3.25、3.26 之间来回切，或者机器上没有管理员权限的情况。IDE 附带的那份我一般不用它当主力，原因很简单：路径藏在 IDE 安装目录里，版本跟着 IDE 升级走，同事之间对不上号。

从 3.21 开始，Windows 平台就不再提供 32 位构建包了，所以能下到的基本都是cmake-3.25.3-windows-x86_64.msi和对应 ZIP。3.25 这个系列一路修到 3.25.3，装就装最后一个补丁版，别停在 3.25.0。补丁版修的都是配置阶段的边界问题，比如某些生成器下策略告警误报，这类问题在你自己工程里极难定位。

提示：同一个项目在不同人机器上跑出不同结果，第一件要核对的就是cmake --version是否一致，而不是先去怀疑CMakeLists.txt。

2.2 编译器与生成器对照：装之前先确定走哪条路

CMake 3.25 支持很多生成器，但 Windows 上常用的就那么几个。选生成器等于选“谁来真正调度编译”。下面这张表是我在装之前会先填的，填完再去下安装包，能少走一大截弯路。

新手最省事的做法是先走Visual Studio 17 2022：生成器名写对、-A x64写对，基本就能配置成功，因为它不需要你提前把cl.exe塞进 PATH。代价是构建慢、目录里生成一堆.vcxproj文件，看日志时噪声大。等你对项目结构熟了，再切Ninja，配置阶段能快好几倍，但也开始要求你把编译环境准备好——这是后面第 5 章要重点说的一类翻车。

还有个容易忽略的点：生成器是有“版本绑定”的。Visual Studio 17 2022这个生成器名是 CMake 3.21 才加进来的，你在 3.19 上敲它，报的就是Could not create named generator。所以版本和生成器必须成对考虑，这也是我坚持在 Windows 上把 CMake 单独装一份、不复用 IDE 版本的原因。

2.3 目录规划与权限：别装进带空格和中文的路径

MSI 默认装在C:\Program Files\CMake，这个路径本身没问题，Program Files 里的空格 CMake 自己能处理。真正有风险的是 ZIP 免安装版：很多人随手解压到桌面或者中文目录下，比如D:\工具\cmake\新建文件夹，然后在某个第三方库的构建脚本里就会出现引号没包住、路径被截断的情况。这类问题不会在cmake --version阶段暴露，而是在链接或者自定义命令里冒出来，非常难查。

我的习惯是 ZIP 版统一定到一个短路径下按版本号分层，像D:\tools\cmake\3.25.3\bin，将来升 3.26 就并列一个目录，切版本只需要改 PATH 顺序，不用删旧版。构建目录（也就是-B指定的那个）也不要放在 OneDrive 同步目录或者被杀毒软件实时扫描的目录里，CMakeCache.txt频繁读写，同步和扫描都会拖慢配置阶段，偶尔还会锁文件导致配置中断。

最后一个清点项是权限。MSI 安装需要管理员权限，ZIP 版则要求你对解压目录有读执行权限；如果你把 ZIP 解压到了别人的用户目录，用另一个账号跑cmake会直接提示找不到可执行文件。这类问题在共用构建机上出现过，排查方向很容易跑偏到“是不是安装包坏了”。

3. 安装 CMake 3.25：MSI 向导、ZIP 解压与首次验证

前面清点完，这一章就是真正动手。两条路我都走过，MSI 适合一步到位，ZIP 适合要控版本的人。下面把两条路的命令和勾选项都写全，照着做基本不会出岔子。

3.1 MSI 安装：向导里那三个勾选项到底选哪个

先确认下载到的是cmake-3.25.3-windows-x86_64.msi，双击进入向导。一路下一步到安装选项页，会看到三个复选框，它们是后面所有 PATH 问题的源头，值得单独说清楚：

• Add CMake to the system PATH for all users：写系统级 PATH，所有账号生效，需要管理员权限。
• Add CMake to the system PATH for the current user：只写当前用户 PATH，不需要动系统环境变量。
• Create CMake Desktop Icon：桌面图标，纯粹好看，不影响使用。

我个人选第二项。原因不是权限洁癖，而是“系统 PATH 一旦写进去就很难判断是谁写的”，将来排查版本冲突时，用户级 PATH 在where cmake的输出里位置更靠后、更好识别。如果你是共用构建机，那就选第一项，保证登录任何账号都能用。

装完之后别急着开项目，先关掉所有已经打开的终端窗口。MSI 修改的是环境变量，已经启动的 cmd 或 PowerShell 进程不会自动刷新，这是新手最常碰到的“明明装了却找不到命令”。新开一个窗口再往下走。

# 版本号：必须显示 3.25.x，不是 3.19 也不是 3.28 cmake --version # 可执行文件位置：确认第一条就是你想用的那一个 where cmake # 生成器清单：确认列表里出现 Visual Studio 17 2022 和 Ninja cmake --help

cmake --version输出里除了版本号，还会带一行版权信息，版本号在首行。where cmake会按 PATH 顺序列出所有同名可执行文件，如果第一条不是你刚装的那个，说明 PATH 里还有别的版本排前面，处理办法在第 4 章。cmake --help会打印一长串内容，重点是往下翻到 “Generators” 那一段，确认你要用的生成器在不在列表里——这一步比看版本号更能提前发现问题。

3.2 ZIP 免安装：解压、加 PATH、固化一个启动脚本

ZIP 版没有安装向导，全靠手动。下载cmake-3.25.3-windows-x86_64.zip之后，我一般会在 PowerShell 里完成解压和 PATH 写入，这样命令是可复现的，不用手点资源管理器。

# 1. 解压到统一的工具目录，路径保持短、不带空格和中文 Expand-Archive -Path "D:\downloads\cmake-3.25.3-windows-x86_64.zip" ` -DestinationPath "D:\tools\cmake" # 2. 把 bin 目录追加到当前用户的 PATH（只影响当前账号） $cmakeBin = "D:\tools\cmake\cmake-3.25.3-windows-x86_64\bin" $oldPath = [Environment]::GetEnvironmentVariable("Path", "User") [Environment]::SetEnvironmentVariable("Path", "$oldPath;$cmakeBin", "User") # 3. 打印结果，确认追加成功且没有重复项 [Environment]::GetEnvironmentVariable("Path", "User")

Expand-Archive的-DestinationPath指定解压根目录，解压后会自动多出一层cmake-3.25.3-windows-x86_64，所以$cmakeBin要比解压目录多一层。SetEnvironmentVariable的第三个参数"User"是关键：写"Machine"就是系统级，需要管理员权限；这里选用户级是为了不给别人添麻烦。最后那行打印不是可有可无的，PATH 字符串超长或者中间有重复分号时，Windows 的行为很不直观，看一眼输出能省掉后面半小时的排查。

注意：追加 PATH 时用分号分隔，不要覆盖原有内容。把$oldPath整个替换掉会导致一堆系统命令找不到，恢复起来很麻烦。

如果你的工作需要频繁在几个 CMake 版本之间切换，可以再补一个小的启动脚本，放在项目根目录，双击就进到已经配好PATH的终端里：

@echo off REM 临时把 3.25.3 提到 PATH 最前面，只在当前窗口生效，退出即恢复 set PATH=D:\tools\cmake\cmake-3.25.3-windows-x86_64\bin;%PATH% cmd /k

set PATH=新路径;%PATH%是前置拼接，等价于把新版本提到最优先。cmd /k表示执行完保留窗口。这种写法只影响当前窗口，不污染系统环境变量，比反复改系统 PATH 安全得多，我一般会在需要复现某个老项目构建结果时用它。

3.3 装完第一件事：三条命令确认版本、路径、生成器

无论走 MSI 还是 ZIP，装完之后的验收动作是同一套：版本、路径、生成器。三条命令在第 3.1 节已经列过，这里补一下每种异常输出意味着什么。

cmake --version打到cmake version 3.19.x，说明 PATH 里有旧版本排在前面，不是安装失败。where cmake只打印一行，但那一行不是你期望的目录，说明 PATH 里只有这一个版本，而你装的另一个压根没进 PATH。cmake --help的生成器列表里没有Visual Studio 17 2022，说明当前生效的 CMake 版本低于 3.21，问题同样回到 PATH 顺序上。

这三条命令跑通，只能说明 CMake 本体可用，还不能说明你的 C++ 工程能构建，因为编译器还没参与进来。下一章处理的就是“怎么让 CMake 3.25 稳定地选中正确的生成器和编译器”，这是从“装好了”到“能用了”之间的那一段路。

4. 配置环境变量与默认生成器：PATH 顺序、CMAKE_GENERATOR 和 Presets

装完 CMake 3.25、三条命令都正常，仍然有一大批人卡在下一步：每次敲cmake -S . -B build都要带一长串参数，忘了带-A x64就生成 32 位工程，忘了带-DCMAKE_BUILD_TYPE=Release就跑出个 Debug 版二进制。这一章解决的就是参数固化问题，把该写在环境变量里的写进环境变量，该写进项目里的写进CMakePresets.json。

4.1 PATH 顺序：旧版本抢跑怎么处理

Windows 的 PATH 是从前到后匹配的，谁排前面谁生效。where cmake输出多行时，第一行就是当前生效的那个。处理顺序冲突有三种做法，我按推荐度排：

第一种，删掉不需要的旧版本 PATH 条目。适合确定不再用旧版的情况，最干净，但要注意别把 IDE 依赖的那份删了，IDE 一般走自己的绝对路径，不受影响。

第二种，把 3.25 的bin目录提到 PATH 最前面。适合多版本并存，缺点是需要手动维护顺序，重装系统后容易忘。

第三种，不改全局 PATH，用第 3.2 节那个启动脚本，或者用完整路径调用D:\tools\cmake\3.25.3\bin\cmake.exe。适合在 CI 脚本或者批处理里锁定版本，缺点是命令行难记。

第三种放在项目脚本里最稳，因为 CI 机器上的 PATH 你控制不了。日常开发我用第二种，因为改一次能管很久。

# 把 3.25.3 从用户 PATH 里摘出来，重新拼到最前面，避免重复 $cmakeBin = "D:\tools\cmake\cmake-3.25.3-windows-x86_64\bin" $oldPath = [Environment]::GetEnvironmentVariable("Path", "User") $parts = $oldPath -split ';' | Where-Object { $_ -and $_ -ne $cmakeBin } $newPath = (@($cmakeBin) + $parts) -join ';' [Environment]::SetEnvironmentVariable("Path", $newPath, "User")

-split ';'把 PATH 拆成数组，Where-Object过滤掉空项和已经存在的同一路径，这一步是为了防止反复执行后 PATH 里堆出一串重复条目。@($cmakeBin) + $parts把目标路径拼到数组头部，再-join ';'还原成字符串。整个操作是幂等的，跑几遍结果都一样，这点在写自动化脚本时很重要。

4.2 环境变量与工具链变量：把手敲的参数固化下来

CMake 3.25 认一批环境变量，优先级低于命令行参数、高于内置默认值。下面这些是我在实际项目里会配的，其余的按需再加。

CMAKE_GENERATOR配置之后，cmake -S . -B build就不用再带-G。但我一般不配这个全局变量，原因是它会让“这个项目到底该用哪个生成器”这件事从项目里跑到了机器上，换台机器行为就变了。更稳妥的做法是写进项目自己的预设文件，也就是下一节。

CMAKE_BUILD_TYPE是另一个高频误用点。它只对Ninja、MinGW Makefiles这类单配置生成器有效；用Visual Studio 17 2022时设置了也不会报错，但完全不起作用，构建出来仍然是 Debug。这个问题藏得深，因为终端上不会有任何提示，只有你发现性能不对时才回头查。

4.3 CMakePresets.json：把参数写进项目里

CMake 3.25 对CMakePresets.json的支持已经比较完整，我现在的做法是：凡是打算提交到仓库、要在多台机器上复现的参数，一律写进预设文件，不靠环境变量，也不靠口头约定。

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

version: 6对应 CMake 3.25 支持的预设文件 schema，用更低版本的 CMake 打开会被直接拒绝，这其实是个好事——版本不匹配当场就暴露，不用等到构建阶段。binaryDir里用${sourceDir}拼接，保证不同人机器上构建目录都在各自的项目根下，不会互相覆盖。architecture只在 VS 系列生成器里生效，等价于命令行的-A x64；cacheVariables里的键值会直接写进CMakeCache.txt，等价于-D参数。

配好之后，命令就简化成两行：

# 用预设配置，不再手敲 -G / -A / -D 一长串 cmake --preset dev-msvc # 用预设构建，--build 后面跟构建预设名 cmake --build --preset dev-msvc

--preset后面跟的是预设里的name字段，不是displayName。想确认项目里有哪些预设可用，敲cmake --list-presets就行，它会读当前目录的CMakePresets.json并列出全部可用预设——这个命令在接手别人项目时特别好用，能立刻知道作者预设了哪几种构建方式。

5. 避坑与排查：五个装完才发作的 CMake 问题

CMake 3.25 本身的安装在 Windows 上其实很顺，真正消耗时间的是装完之后各种“看起来装好了但就是用不了”。下面五条是我在实际环境里反复遇到的，每条按现象、原因、解决写，遇到对应症状可以直接对号入座。

5.1 现象：cmake --version是旧版本；原因：PATH 顺序；解决：where cmake排首项

现象是安装过程没有任何报错，但新开的终端里cmake --version显示的还是 3.1x 甚至 3.10，cmake -G "Visual Studio 17 2022"报找不到生成器。原因不复杂：机器上本来就有另一份 CMake，它的bin目录在 PATH 里排得更靠前，MSI 或 ZIP 加进去的条目被压在后面。Windows 不会提示“有多个版本”，它只按顺序取第一个匹配上的。

解决分三步。第一步where cmake看全部候选和顺序，找出排在真实目标前面的那个路径。第二步判断那份旧版本还有没有用：如果是 IDE 附带的，通常不需要删文件，只要保证它不在全局 PATH 里；如果是以前手动装的，可以在“系统属性—环境变量”里找到并删掉对应条目。第三步重新开一个终端再验证，这一步不能省，环境变量的修改对已打开的进程无效。

还有一个隐蔽变种：where cmake只输出一行，而且路径正确，但版本号还是旧的。这种情况多半是 ZIP 版解压时目录名和预期不一致，PATH 指向的目录里躺着的是另一次解压的旧内容。解决办法是直接看bin目录下的文件修改时间，比对着版本号确认。

5.2 现象：生成器名报错；原因：版本或拼写；解决：先核对 3.21 这条线

现象是执行带-G的配置命令时直接失败，提示找不到指定的生成器。原因通常有三种：CMake 版本低于 3.21，根本不认识Visual Studio 17 2022这个生成器名；生成器名拼写或大小写不一致，比如写成visual studio 17 2022；用了-A参数但生成器本身不接受平台参数。

解决的第一动作永远是先跑cmake --version确认版本，而不是去CMakeLists.txt里找问题。版本低于 3.21 就别挣扎，按 5.1 的办法把 3.25 提到最前面。版本没问题再看拼写，生成器名是区分大小写的，直接从cmake --help的输出里复制最保险，那里面的原名不会出错。

第三种情况单独说一下：-A x64只对 Visual Studio 系列生成器有效，对Ninja或MinGW Makefiles使用会报“不支持该参数”。切生成器的时候记得把不相关的参数一起清掉，否则报错信息会把你往错误的方向带。

5.3 现象：Ninja 找不到编译器；原因：不在开发者环境；解决：先准备编译环境

现象是从普通 PowerShell 里执行cmake -S . -B build -G Ninja，配置阶段报找不到 C 或 C++ 编译器，日志里出现类似编译器未设置的提示。原因很直接：Ninja 生成器不像 Visual Studio 生成器那样自己去定位 MSVC，它要求编译器已经在当前环境里可调用。你从开始菜单直接打开的 PowerShell，PATH 里没有cl.exe，自然就失败了。

解决办法是换一个入口：用开始菜单里对应架构的开发人员命令提示符，或者先执行 VS 安装目录下的批处理脚本，把编译环境变量注入当前会话，再敲 cmake。注入之后的窗口里where cl能打出一行，这一步可以作为验证。如果你不想每次手动点，也可以写一个批处理，把注入和 cmake 配置串起来，双击一次搞定。

有个细节要注意：注入脚本之后不要再用cmd /k之类的嵌套方式启动新窗口，否则环境变量在传递过程中可能丢失。老老实实在同一个窗口里往下敲最稳。

5.4 现象：Release 构建出 Debug 产物；原因：单配置生成器没写构建类型

现象是配置阶段一切正常，构建也成功，跑出来的程序性能明显不对，或者日志里带着调试断言。原因是用了Ninja或MinGW Makefiles这类单配置生成器，但没有显式指定构建类型。单配置生成器的默认构建类型在多数情况下是 Debug，你不写，它就按 Debug 生成。

解决办法是在配置阶段显式带上构建类型，或者在预设文件里把CMAKE_BUILD_TYPE写进cacheVariables，两种做法等价。判断当前缓存里到底是什么类型，可以直接看CMakeCache.txt里的CMAKE_BUILD_TYPE那一行，不用猜。

对应的另一个方向：用Visual Studio 17 2022这类多配置生成器时，配置阶段根本不用写构建类型，写了也不生效。真正决定产物的，是构建阶段的--config参数。用预设构建时，要写的是buildPresets里的configuration字段，而不是CMAKE_BUILD_TYPE。这两个概念混用是新手最常见的认知错位。

5.5 现象：构建目录报不一致；原因：目录被移动或复制；解决：删缓存重建

现象是某个项目昨天还能配，今天换了目录位置或从别人那拷过来之后，配置阶段直接报错，提示缓存目录路径不一致。原因是CMakeCache.txt里记录了配置时的绝对路径，目录一移动，缓存里那些绝对路径就全部失效，CMake 检测到不一致会拒绝继续。

解决办法很简单：删掉构建目录里的缓存文件，重新配置一次。注意只需删CMakeCache.txt和CMakeFiles目录，源码目录里的东西一样都别动。重建的代价是配置阶段多用几秒，比手工去改缓存文件里的路径安全得多。

我的习惯是构建目录一律不进版本控制，build/写进忽略文件。跨机器搬项目时只搬源码和CMakePresets.json，构建目录让对方自己重新生成，这样从根上避免了缓存路径问题。这条经验来自一次拷了整个目录导致构建机白跑半天。

6. 装完怎么验证跑通：一个最小 C++ 工程的三步验收

版本、PATH、生成器都确认过，还差最后一步：让 CMake 3.25 真正驱动一次 C++ 编译，把配置、构建、运行整条链走通。我会用一个只有三行代码的最小工程做验收，因为它能同时暴露生成器选择、编译器定位、构建类型三类问题，而且失败时日志干净，一眼能定位。

先准备两个文件，放在同一个空目录里：

# CMakeLists.txt —— 最低版本卡在 3.25，低于它的 CMake 会直接拒绝配置 cmake_minimum_required(VERSION 3.25) project(hello_cmake LANGUAGES CXX) # 标准交给 CMake 管理，避免手工往编译选项里塞 /std 造成生成器不兼容 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(hello main.cpp)

// main.cpp —— 只做一件事：输出一行字，证明整条构建链通了 #include <iostream> int main() { std::cout << "cmake 3.25 build ok" << std::endl; return 0; }

cmake_minimum_required(VERSION 3.25)这一行是刻意的：一旦机器上生效的是旧版本，配置阶段会立刻停下并告诉你版本不够，比等到构建阶段才报错清晰得多。LANGUAGES CXX只开启 C++ 语言，省掉 C 编译器的探测，配置日志更短。

接着分三步走，用预设或直接命令行都行：

# 1. 配置：显式指定生成器和平台，产物落到 build 目录 cmake -S . -B build -G "Visual Studio 17 2022" -A x64 # 2. 构建：多配置生成器用 --config 选 Release cmake --build build --config Release # 3. 运行：VS 生成器把产物放在配置子目录下 .\build\Release\hello.exe

-S .指定源码目录是当前目录，-B build指定构建目录，两者分离，源码目录里不会多出任何中间文件。--config Release只对多配置生成器有意义，正好和第 5.4 节说的单配置生成器形成对照。运行路径里带Release这一层，是因为 VS 生成器按配置分目录输出，用Ninja时产物会直接落在build根下，路径不一样。

验收成功的标志有三个，缺一不可：配置阶段末尾打印Configuring done和Generating done；构建阶段输出里能看到hello.vcxproj对应的编译和链接步骤；最终程序打印出那行文字。三项都过，说明这台机器上的 CMake 3.25 已经可用。

如果其中某一步失败，按第 5 章的顺序回查：版本不对回 5.1，生成器不认回 5.2，编译器找不到回 5.3，产物行为异常回 5.4，缓存报错回 5.5。这套最小工程的价值在于把问题范围压到最小，等你把同样的命令套到真实项目上，排查依据是同一套。

从那以后我每装一台新机器，都会先建这个三文件的小工程跑一遍，过了再动真实项目，绝不跳过。吃过一次亏之后就不想再靠猜了——那次 IDE 里能构建、命令行里死活配不过，折腾一下午才发现是 PATH 里那具旧版本在捣鬼。希望帮到你。

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