Windows下CMake 3.25安装、PATH与生成器配置指南

简介面向 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_PATHSystem # 装完验证 bin 目录是否落地 Get-ChildItem C:\Program Files\CMake\bin | Select-Object NameADD_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 --version3.25.3 --install-argumentsADD_CMAKE_TO_PATHSystem -y--install-arguments就是把 msi 那套属性透传下去行为和手动装 msi 完全一致。Scoop 默认桶里通常只有最新稳定版要老版本得先加 versions 类的桶命令写成scoop install cmake3.25.3的形式桶没加会直接报找不到。三种方式的差别集中在这几处方式是否需要管理员多版本并存升级方式卸载残留msi系统级安装需要麻烦得手改 PATH装新版覆盖可能留空目录和 PATH 项zip 便携版不需要天然支持换目录改路径删目录即可包管理器视配置而定winget 较弱Scoop 较好一条命令相对干净2.3 安装前先核对VS 与 SDK 的版本搭配CMake 本身只是调度台真正编译的是 MSVC。3.25 里 VS 生成器的名字和本机 Visual Studio 大版本是死绑的VS2019 对应Visual Studio 16 2019VS2022 对应Visual Studio 17 2022。本机只装了 VS2019却写 17 2022configure 会直接告诉你找不到生成器反过来用 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_VERSION10.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 cmakewhere.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.batecho off REM 把 3.25.3 的 bin 目录前置覆盖系统里可能存在的其他版本 set CMAKE_HOMED:\tools\cmake-3.25.3 set PATH%CMAKE_HOME%\bin;%PATH% REM 打印一次版本确认切换生效 cmake --version REM 保留一个子 shell退出这个窗口不影响外部环境 cmd /kset 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 自己认的几个环境变量除了 PATHCMake 还会读一批同名环境变量作为缓存变量的初始值。这些变量在 configure 时如果命令行没显式传-D就会拿环境变量顶上——用好了能少敲一长串参数用不好就是玄学报错。环境变量作用常用值CMAKE_PREFIX_PATH找依赖包的额外搜索根目录D:\libs\opencv;D:\libs\boostCMAKE_GENERATOR默认生成器省掉每次-GNinjaCMAKE_GENERATOR_PLATFORMVS 生成器的平台参数x64CMAKE_BUILD_TYPE单配置生成器的构建类型ReleaseCMAKE_TOOLCHAIN_FILE交叉编译或 vcpkg 工具链文件工具链文件绝对路径CMAKE_MAKE_PROGRAM指定 ninja.exe 或 make.exe 位置D:\tools\ninja\ninja.exe设置方式和普通环境变量一样用户级用# 用户级持久化新开的终端生效当前会话要立刻生效就再手动赋一次 $env:CMAKE_GENERATOR [Environment]::SetEnvironmentVariable(CMAKE_GENERATOR, Ninja, User)这里有个取舍要说清楚CMAKE_BUILD_TYPE设成全局环境变量对单配置生成器Ninja、MinGW Makefiles很方便但对多配置生成器Visual Studio 系列完全无效因为后者在 build 阶段用--config决定。我见过有人把CMAKE_BUILD_TYPEDebug写进系统环境变量结果所有 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 hostx64是另一个维度它控制的是编译过程本身用 64 位工具链工程大、头文件多的时候能避免编译器内存不够和-A不冲突可以一起用。Ninja 是单配置的速度快但要求cl.exe已经在 PATH 里也就是必须在开发者命令提示符里执行# 单配置生成器必须显式给构建类型否则默认是空编译选项里没有优化 cmake -S . -B build-ninja -G Ninja -DCMAKE_BUILD_TYPERelease # Ninja 下不需要 --config直接构建 cmake --build build-ninja这一步最容易出的错是在普通 PowerShell 里跑 Ninja报错是CMAKE_CXX_COMPILER not set或者干脆找不到cl。解决办法不是硬指定编译器路径而是从开始菜单里找那个带 x64 字样的开发者命令提示符环境变量都是它初始化好的。实在要在普通终端里跑就在 configure 时传-DCMAKE_C_COMPILERcl -DCMAKE_CXX_COMPILERcl但这条路依赖 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在多配置生成器里等价于-AcacheVariables里的东西等价于-D一个字段对应一个命令行参数对照着看就明白。用起来就两条命令# 按预设 configure等价于那一长串 -G -A -D cmake --preset vs2022-x64 # 按预设 buildconfiguration 已经在文件里指定 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_PROGRAMninja 绝对路径。判断环境有没有初始化好敲一句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_castlong(__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 --version首行为 3.25.x路径唯一where.exe cmake只有一条指向预期目录生成器可用cmake --help的 Generators 段能列出目标生成器编译器可见where cl在开发者提示符下有输出最小工程通过configure / build / ctest 三步全部返回 0新语法可用工程里含block()且 configure 成功无未知命令报错这张表我一般会贴在工位旁边新机器、重装系统、换笔记本都走一遍五分钟的事比事后查为什么只有我这台编不过省太多时间。从那以后我每次装 CMake 都强制走一遍这个最小工程哪怕只是升个补丁号——版本号敲出来对不代表生成器、编译器、SDK 三方都对得上跑一次比看十行--version踏实。希望对你有帮助这份 Windows 侧的 3.25 安装包拿过去按上面顺序装、配、验一遍环境就算立住了。本文还有配套的精品资源点击获取