简介这是 CMake 3.27.9 在 Windows x86_64 平台下的官方发行压缩包适合需要在 Windows 环境使用或学习 CMake 构建系统的开发者。压缩包内共 2000 个文件其中 1175 个 txt 文本文件与 825 个 html 帮助文档html 部分涵盖 cmake-generator-expressions、cmake-buildsystem、cmake-presets 等核心主题txt 文件则提供命令行工具说明与补充阅读材料便于本地离线查阅。整包大小约 41.95MB体积紧凑下载后即可解压使用。目前已有 379 人学习下载。借助这份包体读者可快速获得完整的 CMake 3.27.9 文档体系不必逐页在线查找无论是安装配置、生成器表达式还是构建系统与预设管理都能从本地 html 文档中找到权威说明同时配合 txt 手册加深理解适合希望系统掌握 CMake 或需要离线参考资料的开发人员。1. 为什么 Windows 上装 CMake我会先去拿 cmake-3.27.9-windows-x86_64.zip如果你在 Windows 上做 C/C 开发大概率被 CMake 卡过一道官网默认给的是 .msi 安装包双击一路 Next 就能装但真到用的时候公司内网受限、CI 批量部署、或者想同时留两个 CMake 版本时msi 的注册表、卸载记录和必须的管理员权限就特别碍事。cmake-3.27.9-windows-x86_64.zip 是官方发布的免安装分发包解压后 cmake、cmake-gui、ctest、cpack 全在 bin 目录里不需要写入注册表删掉目录即卸载。本文就围绕这份 zip 讲三件事它和 msi 到底差在哪、怎么在 Windows x86_64 上快速跑通、以及那些能让新手和熟手都翻车的隐藏坑。适合本地开发、离线部署、想多版本共存的人。2. 解压即用的免安装 CMakezip 包和 installer 实质差在哪2.1 同是 3.27.9为什么我不用 .msi 安装包先把结论放前面3.27.9 属于 CMake 3.27 系列比较靠后的补丁版本功能上 zip 分发包和同版本 msi 没有任何差异差异全在分发方式和系统集成层面。对比项zip 分发包msi 安装包安装方式解压即用不写注册表需要 UAC 管理员权限写安装注册表卸载方式删除目录控制面板卸载可能残留注册项多版本共存完美目录隔开即可麻烦需要轮换 PATH离线/内网部署拷贝 zip 过去就能用需要静默安装参数依赖 Windows Installer 服务PATH 迁移改目录名即可需要改注册表里的安装路径适合场景CI、便携工具、多版本切换单机个人开发、需要开始菜单快捷方式我一般会建议团队里做自动化、做 CI 的人一律用 zip 分发包。原因很现实构建机上装 msi 需要管理员权限而很多 Windows 构建 agent 跑在普通账户下zip 就只要把文件落到指定目录改一下 PATH问题就消失了。还要明确一点标题里的 x86_64 指的是 64 位 Intel/AMD 架构。现在的 Windows 绝大多数是 x64 系统选这个包没错如果你手里是 Windows on ARM 设备那要考虑 ARM64 版本x86_64 在 ARM 上即使能模拟运行构建速度也会有损失。2.2 解压后目录里有什么bin、doc、share 各自的角色zip 解压后会得到一个 cmake-3.27.9-windows-x86_64 目录核心内容大致是这样cmake-3.27.9-windows-x86_64/ ├── bin/ │ ├── cmake.exe │ ├── cmake-gui.exe │ ├── ctest.exe │ ├── cpack.exe │ └── ... ├── doc/ │ └── cmake/ │ ├── html/ # 手动文档 │ ├── index.html │ └── ... ├── share/ │ ├── cmake-3.27/ │ │ ├── Modules/ # 内置 FindXXX.cmake 与工具链文件 │ │ └── ... │ ├── vcpkg/ # 部分版本会有 ports 相关文件 │ └── ...bin 是命脉后面配置 PATH 就指向这里。doc 里的 HTML 文档值得留一份很多人在线文档访问受限时直接用本地 index.html 查 CMake 命令参考比搜索引擎靠谱。share/cmake-3.27/Modules 目录是内置模块仓库你写的 find_package 指令实际就是去这里找对应的 FindXXX.cmake 或者通过配置文件匹配的如果这个目录损坏最典型的表现是“所有 find_package 全部失效”。2.3 CMake 和 Makefile 是什么关系生成器与编译器的分工很多人被“cmake 和 makefile 区别”这个问题绕晕。简单说CMake 不负责编译它只负责生成构建系统文件真正的编译任务由生成器委托给 Visual Studio、Ninja 或 MinGW Make 去执行。在 Linux 上CMake 默认生成 Makefile然后你执行 make在 Windows 上情况完全不一样——没有安装 make 时你执行 cmake -S . -B build 可能直接报错因为默认生成器在不同平台上不一样。具体到这份 zip 包cmake.exe 会通过内置的 platform 检测逻辑判断当前是 Windows 哪个编译器环境然后选择合适的生成器。常见的有Visual Studio 17 2022生成 .sln/.vcxproj交给 MSBuild 构建。Ninja生成 build.ninja配合 cl.exe 或 MinGW-w64 的 gcc 使用速度最快。MinGW Makefiles配合 MinGW-w64 环境行为接近 Linux 下的 make。所以你看CMake 做的事比 makefile 高一阶makefile 是给 make 读的输入而 CMake 的输入是 CMakeLists.txt输出可以是 makefile、ninja 文件或 VS 工程。我用 zip 版之后最明显的感受是不用再管系统里有没有 make 了因为分发包自带全套生成器模板只要目标编译器在 PATH 里就能生成对应构建系统。2.4 把 bin 写进 PATH用户变量与系统变量的选择zip 版 CMake 唯一需要手动做的事就是把 bin 目录加入 PATH。常见做法是加用户变量而不是系统变量# 把 CMake 的 bin 目录追加到用户级 PATH $cmakeBin C:\tools\cmake-3.27.9-windows-x86_64\bin [Environment]::SetEnvironmentVariable( Path, [Environment]::GetEnvironmentVariable(Path, User) ;$cmakeBin, User ) # 验证刚才是否写入成功 [Environment]::GetEnvironmentVariable(Path, User)选用户变量的原因是避免动系统级 PATH。系统级 PATH 一旦写坏整台机器的命令都可能失效我见过不止一次因为安装软件往系统 PATH 里乱写导致 git、python 全部找不到的翻车现场。用户变量只影响当前账户权限要求低也不需要在管理员终端里执行。注意一点SetEnvironmentVariable 只改注册表里的持久化值不会影响当前已经打开的终端。改完必须新开一个 PowerShell 或 cmd 窗口再执行 cmake --version 才有效——这是 Windows 环境变量广播机制的老毛病等一会儿或者重启终端都行别在同一个窗口里干等。提示如果新开终端仍然找不到 cmake执行 where cmake 看看是不是被 PATH 前面某个旧版本拦截了。多版本共存时PATH 里排在前面的那个生效。3. 在 Windows x86_64 上从解压到跑通第一个 CMake 工程完整步骤3.1 下载、校验与解压先算哈希再动手拿到 cmake-3.27.9-windows-x86_64.zip 后别急着解压。我从 3.20 版本开始养成一个习惯先校验哈希再解压。CMake 官网每个分发包都带 SHA-256 校验值下载页旁边就能找到。你在内网镜像站下载时镜像站一般也会附一个 .sha256 文件。# 计算下载文件的 SHA-256 Get-FileHash .\cmake-3.27.9-windows-x86_64.zip -Algorithm SHA256 # 输出示例真实值以官网为准 # Algorithm Hash Path # ---------- ---- ---- # SHA256 4C1F...替换为实际值...AB3F cmake-3.27.9-windows-x86_64.zip # 用 Expand-Archive 解压到 D:\tools 目录 Expand-Archive -Path .\cmake-3.27.9-windows-x86_64.zip -DestinationPath D:\tools -Force校验这个动作不是强迫症。构建工具链是最容易被偷换和损坏的目标哈希对不上大概率是下载中断或者镜像同步不完整这时候解压出来的 cmake.exe 在配置阶段会出现各种诡异报错很难查。Expand-Archive 的 -Force 参数会在目标目录名冲突时直接覆盖适合重复解压的场景。解压路径有一个很实在的建议不要放在带空格或中文的路径下比如 C:\Program Files\ 或 D:\软件\。CMake 自身能处理带空格的路径但你后面用第三方工具链或脚本时会遇到很多不处理空格的程序血泪教训。我一般放在 C:\tools\ 或 D:\tools\ 这种纯 ASCII 短路径下后面所有构建过程都省心。3.2 配置与生成-S、-B、-G、-A 四个参数一次讲清进入一个带 CMakeLists.txt 的工程目录执行配置生成。以最简工程为例# CMakeLists.txt最小示例 cmake_minimum_required(VERSION 3.16) project(cmake_zip_demo LANGUAGES CXX) add_executable(demo main.cpp)main.cpp 随便写个 hello world。然后执行第一次配置# 进入工程目录 cd D:\work\cmake_zip_demo # 用 Visual Studio 17 2022 作为生成器生成 x64 架构的构建系统 cmake -S . -B build -G Visual Studio 17 2022 -A x64这里的四个参数对应四类常见诉求-S .指定源码目录即 CMakeLists.txt 所在目录。-B build指定构建目录所有生成物CMakeCache.txt、.sln、.vcxproj都会落在 build 里。-G Visual Studio 17 2022指定生成器。在 Windows 上如果不指定CMake 会按优先级自动挑一个但自动挑到的未必是你要的。-A x64指定 Visual Studio 生成器的平台架构。这个参数只对 VS 生成器有效Ninja 和 MinGW Makefiles 不认它。如果你没装 Visual Studio 只装了 Build Tools也可以把生成器换成 Ninja 配合 cl.exe 使用但前提是编译环境变量要提前加载好。判断当前有哪些可用生成器执行cmake --help输出末尾会发现一行The following generators are available on this platform后面列出的就是当前可用列表。这一步能避免很多“为什么报 generator 不存在”的疑问。生成成功后构建cmake --build build --config Release注意--config Release对 VS 生成器是必须的因为 VS 工程支持多配置Debug/Release 是在构建期选的Ninja 则大多是单配置生成器需要在配置阶段用-DCMAKE_BUILD_TYPERelease指定。第一次用 zip 版 CMake 的人经常在这里弄混看到 Release 目录下没有 exe 就以为构建失败。3.3 用 CMake GUI 看配置过程缓存变量改完记得点 Generate命令行一步到位当然快但如果你想看清配置过程或者想改缓存变量bin 目录里的 cmake-gui.exe 是很好的可视化入口。双击打开后界面分几个区域Where is the source code填源码目录。Where to build the binaries填构建目录一般填源码目录下的 build 子目录。点击 Configure第一次会让你选生成器这里跟命令行 -G 参数一致。Configure 完成后界面会列出所有缓存变量例如 CMAKE_BUILD_TYPE、CMAKE_INSTALL_PREFIX。改完变量后必须再点 Generate否则 CMakeLists.txt 的后续逻辑不会应用最新值。GUI 里最容易踩的坑是Configure 报错后很多人直接改界面上的变量忽略下方输出框里的错误原因。比如报No CMAKE_CXX_COMPILER could be found这时候改什么变量都没用要先确认生成器选择和编译器是否匹配。输出框里的红色文字才是关键界面上变量列表只是结果。我通常在给别人演示 CMake 工作时用 GUI因为能直观看到变量从哪里来、改了什么。自己干活时基本用命令行效率高而且便于记录到脚本里。3.4 构建、ctest、cpack验证整包可用zip 版和 msi 版在功能上没有任何阉割bin 目录里能看到的可执行文件都是完整的。验证整包可用除了 cmake 本身建议把 ctest 和 cpack 也过一遍# 假设上面已经构建过 build 目录运行测试 ctest --test-dir build -C Release --output-on-failure # 生成安装包需要工程里写了 install 规则 cpack --config build/CPackConfig.cmakectest 的 --output-on-failure 是必加参数它保证测试失败时能看到具体输出而不是一个干巴巴的 Failed 状态。cpack 在国内用的相对少但它其实是 CMake 自带的一套打包工具能生成 ZIP、NSIS 安装包等格式很多开源项目发布的 Windows 安装包就是它做出来的。提示如果工程没有启用测试ctest 会报 “no tests were found”这是正常的不是安装包坏了。4. Windows 版 CMake 的常见问题排查PATH、编译器与版本缓存4.1 新开终端 cmake --version 还是老版本现象明明刚下载了 3.27.9 并配好 PATH终端里执行 cmake --version 显示的却是老的 3.20 或者干脆是“不是内部或外部命令”。原因两个常见来源。一是 PATH 里多个 CMake 并存旧版本的 bin 排在新版本前面二是 SetEnvironmentVariable 改的是用户变量而系统变量里已有旧 CMake系统变量优先级更高。解决先执行 where cmake 看实际调用的是哪一个路径。如果是系统变量里的旧版找到它并删除如果是 PATH 顺序问题把新版本目录移动到前面。我一般把 CMake 放在C:\tools\cmake-3.27.9-windows-x86_64\bin然后在所有软件安装器插入的系统变量之后追加这一项同时确保没有第二个 cmake 存在于 PATH 里。4.2 Configure 报 No CMAKE_CXX_COMPILER could be found现象执行 cmake -S . -B build 后输出在 “Detecting CXX compiler ABI info” 附近卡住随后报找不到 C 编译器。原因CMake 本身不管编译它要去找编译器。在 Windows 上如果选了 Visual Studio 生成器但没有安装对应版本的 C 桌面负载或者选了 Ninja/Makefiles 生成器但没有把 cl.exe 或 gcc.exe 放进 PATH都会报这个错。解决先确认用的是哪个生成器。VS 生成器要装 Visual Studio 的“使用 C 的桌面开发”工作负载Ninja 生成器需要先进入 x64 Native Tools Command Prompt或者手动把 cl.exe 所在路径加进 PATH。这里最省事的组合是Visual Studio 生成器 安装好 C 负载它是自洽的不依赖 PATH 里的编译器。4.3 64 位 zip 包在 32 位进程里跑不了现象双击 cmake-gui.exe 提示“不是有效的 Win32 应用程序”或者命令行执行 cmake.exe 闪退。原因cmake-3.27.9-windows-x86_64.zip 里是 64 位二进制要求操作系统是 64 位 Windows。如果你在 32 位进程比如 32 位 cmd 或 32 位打包脚本里调用依然可能出现兼容性问题但最常见还是系统本身是 32 位。解决确认系统位数PowerShell 里查看$env:PROCESSOR_ARCHITECTURE输出 AMD64 就是 64 位。系统确实 32 位的话换用 CMake 官方的 x86 分发包。注意标题写的是 x86_64默认就该用在 64 位系统上这条主要是提醒那些把 zip 拷到嵌入式设备或老旧 Win7 32 位机器上的人。4.4 项目改了 CMakeLists.txt重新配置却像没改一样现象修改 CMakeLists.txt 里的选项再次执行 cmake -S . -B build新配置没有生效还是旧行为。原因构建目录里的 CMakeCache.txt 会缓存大量变量和检测结果。CMake 的增量配置逻辑是如果缓存里已有某变量值且你不在命令行重新指定它就继续沿用旧值。这就是很多人说的“CMake 缓存玄学”。解决最直接的办法是删掉 build 目录重新配置如果只想重置缓存而保留构建文件可以执行cmake --fresh -S . -B build。--fresh 是 CMake 3.24 开始引入的参数3.27.9 完全支持它的效果等同于删除 CMakeCache.txt 后重新跑一遍配置流程等于给构建系统吃了一粒后悔药。注意 --fresh 必须写在 -S 前面顺序反了会直接报错。4.5 配置时下载依赖失败构建卡在 FetchContent 阶段现象工程用了 FetchContent 或 find_package 去拉第三方库配置过程看起来正常但卡在下载阶段最后报超时或校验失败。原因CMake 的 FetchContent 默认从 GitHub 等源下载国内网络环境经常连不上或者极慢。这跟 zip 包本身无关是网络问题。解决常见做法是在配置时指定镜像源-DFETCHCONTENT_SOURCE_DIR_NAME本地路径或者把第三方库先用 git clone 到本地再通过 FETCHCONTENT_SOURCE_DIR 指过去。这属于规避网络依赖的常规手段和 CMake 版本关系不大但用 zip 分发包做离线部署时几乎必遇到提前把依赖源码备齐能省大量时间。5. 让 zip 版 CMake 变成便携构建箱多版本切换与工具链绑定zip 版最大的隐藏价值不是“免安装”而是它让多版本切换变得异常干净。我电脑上常年放着 CMake 3.16、3.24、3.27 三套目录目录名里带版本号互不干扰。切换工具就是一段批处理脚本echo off rem 切换 CMake 版本到 3.27.9 set CMAKE_HOMED:\tools\cmake-3.27.9-windows-x86_64 set PATH%CMAKE_HOME%\bin;%PATH% cmake --version原理很简单当前终端里把目标版本的 bin 目录插到 PATH 最前面cmake 命令立刻变版本关闭终端不影响全局配置。corporate 环境里不想动用户变量时这个临时切换方案尤其好用——每个项目一个构建脚本脚本开头指定自己的 CMake 路径完全规避版本冲突。再进一步我会把编译器也放进这个便携箱。比如把 MinGW-w64 解压到D:\tools\mingw64构建脚本里同时把D:\tools\mingw64\bin加进 PATH然后执行cmake -S . -B build -G MinGW Makefiles -DCMAKE_BUILD_TYPERelease cmake --build build这样整个目录拷到任何一台 64 位 Windows 机器不装任何软件就能构建。做这件事最深的体会是CMake 的 zip 分发包是少有的官方把“绿色化”做得这么彻底的软件不用破解、不用绿化官方就是分发包形态。但有几个细节我要特别叮嘱一是便携箱路径里绝不能有空格和中文二是把编译器也纳入时要确认编译器版本和 CMake 版本兼容比如太老的 CMake 不认识新 GCC 的某些特性三是每次挪动目录后旧的 build 目录最好删掉重新配置因为 CMakeCache.txt 里记录了绝对路径。踩过的教训是有一回我把C:\tools改名成D:\dev_tools然后所有旧 build 目录集体失效当时以为是 CMake 坏了折腾半天才发现是缓存里的绝对路径全部指向旧位置。从那以后编译生成产物我一律不跨目录搬运要么重建要么重新配置。希望这篇能帮你少走这段弯路把 zip 版 CMake 当成一个真正的便携构建箱来用。本文还有配套的精品资源点击获取