简介这是为 Windows 64 位开发者准备的 CMake 3.17.1 免安装包解压即用内置 cmake、ctest、cpack 等可执行程序适合需要快速搭建跨平台构建环境、又不希望手动安装配置的开发场景。压缩包约 32.47MB包含 6169 个文件主体为 txt、html、rst 格式的官方帮助文档以及 cmake 模块与模板脚本另有少量配置、测试和可执行文件可支撑项目配置、测试与打包等常见操作。已有 1187 人浏览学习说明其在 C/C 项目构建与 Visual Studio、Ninja 工具链切换场景中有一定参考价值。资源内附完整命令手册、模块说明与策略文档遇到生成器参数、变量定义或编译选项等问题时可离线查阅也能直接借鉴示例模板减少重复配置提升多平台项目的构建效率。1. 免安装版 CMake 到底香在哪解压即用、多版本并存、不污染系统很多人在 Windows 上用 CMake 的第一反应是去官网下安装包一路 Next装完再手动勾选 PATH。但真正在多个项目、多台电脑之间横跳的开发者需要的往往不是「装好一个 CMake」而是一个能随手解压、随手扔掉的工具包。cmake-3.17.1-win64-x64.zip 就是这样的东西CMake 3.17.1 的 Windows x64 免安装包解压后 bin 目录里就是 cmake.exe、cmake-gui.exe、ctest.exe 和 cpack.exe。它对系统最大的贡献是不写注册表、不需要管理员权限、不偷偷改 PATH想换版本就整个目录删掉干干净净。标题里的「官网最新版」说的是这个包发布时点上的最新版现在官网早就迭代到更高版本了但这恰恰是免安装包的核心价值——按需锁版本。老项目复现、CI 环境固定版本、多版本并存测试都不需要跟着最新版跑。你要做的只是准备一个编译器CMake 自己负责把 CMakeLists.txt 翻译成对应构建工具的脚本。接下来我把这个包从解压到跑通全流程走一遍包括我踩过的坑。2. 先搞清楚 CMake 在 Windows 上的角色生成器、编译器与构建流程在动手敲命令之前先把 CMake 在 Windows 工具链里的定位说清楚。这直接决定你后面选哪个生成器、遇到报错时往哪个方向猜。2.1 CMake 不是编译器它是个「构建系统生成器」有个非常常见的误解下载了 CMake 就能编译 C 了。不对。CMake 自己一行代码都不编译它只负责读 CMakeLists.txt然后替你生成一套 Makefile、Ninja 构建脚本或者一个 Visual Studio 的 .sln 工程文件。真正调用的还是你系统里的编译器MinGW 的 g.exe或者 VS Build Tools 里的 cl.exe。所以 makefile 和 cmake 的区别就很好理解了makefile 是写给 make 看的具体构建规则一个平台一套写法换编译器基本要重写CMakeLists.txt 是写给 CMake 看的抽象描述同一份文件到 Windows 能生成 VS 工程到 Linux 能生成 Makefile。你真正要装的是编译器CMake 的工作是找到编译器、检查它能不能用、再生成构建脚本。如果你只装了 CMake 而没装任何编译器配置阶段就会卡死在编译器检测上。这就是为什么我把编译器、CMake 当成两套独立的东西管理。CMake 换版本不影响编译器编译器升级也不会动 CMake。一个最小可用的 CMakeLists.txt 长这样cmake_minimum_required(VERSION 3.10) project(HelloDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(hello main.cpp)project(... LANGUAGES CXX)这一段很关键它告诉 CMake这个项目需要 C 编译器。如果机器上没有可用的 C 编译器CMake 在这里就会直接报错而不是等你编译时才炸。set(CMAKE_CXX_STANDARD 17)指定 C 标准CMAKE_CXX_STANDARD_REQUIRED ON表示编译器不支持 C17 就报错不能自己降级。2.2 免安装包与安装版的差别注册表、PATH 与 GUI官方安装版会往系统里写注册表项、生成卸载入口安装过程还会问你要不要把 CMake 加进 PATH。这个 zip 版就三个词解压、用、删。它和安装版用的是同一套构建产物bin 目录下 cmake.exe、cmake-gui.exe、ctest.exe、cpack.exe 全都在share/cmake-3.17/ 里有完整的模块和模板文件功能上没有缩水。我见过有人把免安装版理解成「绿色精简版」担心被砍功能。实际上它只是打包方式不同安装版能用的功能这里一个不少。解压后目录结构大致是这样D:\tools\cmake-3.17.1-win64-x64 ├─ bin │ ├─ cmake.exe │ ├─ cmake-gui.exe │ ├─ ctest.exe │ └─ cpack.exe └─ share └─ cmake-3.17 ├─ modules ├─ templates └─ ...唯一需要你自己动手的是把 bin 目录加进 PATHcmake-gui 也在这个目录里。从使用角度说这个 zip 版和安装版没有任何功能差别区别只在环境配置方式。另外强烈建议解压到纯英文路径比如 D:\tools\ 下面。中文路径或者带空格的路径在部分老版本工具链里会出些莫名其妙的问题后面避坑章详细说。2.3 三个常见生成器怎么选MinGW Makefiles、Visual Studio、NinjaCMake 在 Windows 上常用的生成器有三个选哪个取决于你装了哪个编译器。生成器底层工具适合场景编译命令MinGW Makefilesgcc/g mingw32-make装了 MinGW-w64不想碰 VScmake --build buildVisual Studio 16 2019MSBuild cl.exe用 MSVC 生态做完整调试cmake --build build --config ReleaseNinjaninja.exe 任意编译器追求编译速度配合 VS Code 舒服ninja或cmake --build build选型原则我一般是这样机器上有 VS 2019 就优先 Visual Studio 生成器只装了 MinGW-w64 就用 MinGW Makefiles如果你已经装了 Ninja想享受增量编译的快感就选 Ninja。CMake 初次配置时用 -G 参数指定生成器比如cmake -G MinGW Makefiles -S . -B build如果你不确定自己机器支持哪些生成器先跑一句cmake --help输出末尾会列出所有可用的生成器列表。Windows 下想只看 Visual Studio 相关的结果cmake --help | findstr Visual Studio注意cmake --help列出来的生成器是「CMake 认识的」不是「你机器可用的」。比如它列出 Visual Studio 17 2022但你机器没装 VS 2022真去用还是会报错。判断可用性最直接的办法就是看对应的编译器在不在 PATH 里。3. 把 cmake-3.17.1-win64-x64.zip 跑起来解压、PATH 与第一个构建这章是实操主线跟着走一遍你能在命令行里完成第一个 CMake 构建顺手把 VS Code 的集成也搭好。3.1 解压与目录规划建议放在纯英文路径先把包解压到 D:\tools 下。Windows 10 1803 以后的系统自带 tar 命令可以直接解压 zipmkdir D:\tools tar -xf cmake-3.17.1-win64-x64.zip -C D:\tools dir D:\tools\cmake-3.17.1-win64-x64\bintar -xf的-C参数指定解压目标目录解压出来的目录名就是 cmake-3.17.1-win64-x64直接和包名对应。最后一句 dir 是确认 bin 里确实有 cmake.exe。如果你更喜欢 PowerShell也可以Expand-Archive -Path .\cmake-3.17.1-win64-x64.zip -DestinationPath D:\tools解压之后建议顺手看一眼环境变量里的 PATH看 D:\tools 在不在里面。解压路径前面提过别放中文路径别放带空格路径。这一步翻车了后面所有坑都会加倍。3.2 配置 PATH 的两种方式临时 set 与永久 setx配置 PATH 有两种方式。临时方式适合只在这个终端窗口里用set PATHD:\tools\cmake-3.17.1-win64-x64\bin;%PATH% cmake --versionset 命令只对当前 cmd 窗口有效窗口一关就失效。好处是不污染环境坏处是每次开新窗口都得重来一遍。永久方式用 setx 写进用户环境变量setx PATH D:\tools\cmake-3.17.1-win64-x64\bin;%PATH%这里有个血泪经验setx 会把变量值拼接后写入注册表但值超过 1024 字符会被截断。如果你 PATH 本来就长setx 之后可能导致后面一堆路径丢失系统命令都找不到了。更稳妥的做法是走 GUIWindows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量在「用户变量」的 Path 里点新建把D:\tools\cmake-3.17.1-win64-x64\bin加进去然后确定。不管用哪种方式改完 PATH 一定要「新开一个终端窗口」再验证。setx 只影响后续新进程已经开着的 cmd 窗口读不到新值。验证命令where cmake cmake --versionwhere cmake会列出所有被 PATH 命中的 cmake.exe 路径。如果同时出现了多个版本的 cmake你就要注意执行顺序Windows 按 PATH 里的先后顺序匹配。看到一个 3.17.1 路径说明这个免安装包生效了。3.3 写一个最小 C 项目并用命令行构建创建一个测试目录放两个文件。main.cpp#include iostream int main() { std::cout hello from portable cmake std::endl; return 0; }CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(PortableHello LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(hello main.cpp)如果编译器是 MinGW-w64配置加编译一条龙cmake -S . -B build -G MinGW Makefiles -DCMAKE_BUILD_TYPERelease cmake --build build .\build\hello.exe-S .指定源码目录是当前目录-B build指定构建目录是 build 子目录。CMake 会在 build 里生成 CMakeCache.txt 和 Makefile源码目录保持干净这是官方推荐的 out-of-source 构建方式。-DCMAKE_BUILD_TYPERelease设置优化级别对应 g 的-O3。最后cmake --build build是 CMake 的统一编译入口它对不同生成器做了封装不用手动去调 make 或 ninja。如果你用的是 Visual Studio命令换成cmake -S . -B build -G Visual Studio 16 2019 -A x64 cmake --build build --config Release .\build\Release\hello.exe注意-DCMAKE_BUILD_TYPERelease在这里不生效因为 VS 是多配置生成器Debug/Release 是运行时用--config指定的产物路径也会多一级Release。3.4 在 VS Code 与 Visual Studio 里接上这个 CMakeVS Code 装好 C/C 扩展和 CMake Tools 扩展后需要告诉它 CMake 可执行文件的路径。打开设置界面搜cmake.cmakePath改成{ cmake.cmakePath: D:\\tools\\cmake-3.17.1-win64-x64\\bin\\cmake.exe, cmake.generator: Ninja }cmake.generator可以指定默认生成器。填 Ninja 的前提是你机器上装了 ninja.exe 并在 PATH 里没装的话不填或者用 MinGW Makefiles 也行。CMake Tools 扩展左下角状态栏会显示当前 Kit点一下可以选编译器它内部本质上还是调用这个 cmake.exe 去配置和构建。Visual Studio 里想用这个免安装包最省事的方式是先用命令行生成 VS 工程然后直接打开 .sln。也可以让 VS 直接打开 CMakeLists.txt 所在文件夹但 VS 会自动找 PATH 里的 cmake.exe。如果 VS 没找到可以在 CMakeSettings.json 里显式指定{ configurations: [ { name: x64-Release, generator: Ninja, cmakeExecutable: D:\\tools\\cmake-3.17.1-win64-x64\\bin\\cmake.exe } ] }VS Code 和 Visual Studio 两条路都走通之后你就基本摆脱了 IDE 对 CMake 版本的锁定了。底层换哪个版本的 CMake只改一个路径就够。4. 实战用免安装 CMake 编译一个 OpenCV 风格的三方库项目很多人学 CMake 的终极诉求是编译 OpenCV、编译 Qt 项目这类三方库。这章用一个「OpenCV 风格」的库项目模板把免安装 CMake 在复杂场景下的用法讲透。4.1 为什么要现场编译而不是直接下二进制包有人会问OpenCV 官网不是有现成的 Windows 包吗为什么还要自己 CMake 编译答案通常是官方包是用 MSVC 编译的 Release 版不带 Debug也不含扩展模块。你用 MinGW 去连官方包链接阶段全是「未定义的引用」因为 MSVC 的 .lib 和 MinGW 的 .a 二进制格式不兼容。反过来你想要自定义 GPU 模块、TBB、OpenMP或者想把 Qt 后端的 highgui 编进去也得走源码编译。用免安装 CMake 做这类编译正合适。因为它不绑定任何特定编译器配置阶段让它检测 MinGW 就用 MinGW检测到 MSVC 就用 MSVC完全看 build 目录里缓存的 CMAKE_CXX_COMPILER 指向谁。这就是免安装包在复杂项目里的核心优势编译器路径你是自己管的CMake 版本你是自己锁的。4.2 一份能跨生成器的 CMakeLists.txt 模板给你的库项目准备一个最小但五脏俱全的 CMakeLists.txtcmake_minimum_required(VERSION 3.17) project(MyAwesomeLib VERSION 1.0.0 LANGUAGES C CXX) option(MYAWESOME_BUILD_SHARED Build shared library ON) option(MYAWESOME_BUILD_TESTS Build tests OFF) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) if(MYAWESOME_BUILD_SHARED) add_library(myawesome SHARED src/myawesome.cpp) else() add_library(myawesome STATIC src/myawesome.cpp) endif() target_include_directories(myawesome PUBLIC include) if(MYAWESOME_BUILD_TESTS) enable_testing() add_executable(test_core tests/test_core.cpp) target_link_libraries(test_core PRIVATE myawesome) add_test(NAME test_core COMMAND test_core) endif() install(TARGETS myawesome RUNTIME DESTINATION bin LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) install(DIRECTORY include/ DESTINATION include)这里面的option()就是 OpenCV 那种WITH_CUDA、BUILD_opencv_python选项的官方实现方式。命令行里通过-DMYAWESOME_BUILD_TESTSON控制和-DWITH_CUDAON是同一个逻辑。add_library(myawesome SHARED ...)控制动态库还是静态库OpenCV 编译时那个BUILD_SHARED_LIBS选项本质也是这个开关。install()规则决定cmake --install之后头文件和库文件落在哪些目录。4.3 命令行编译流程与缓存变量说明完整流程cmake -S . -B build -G MinGW Makefiles \ -DCMAKE_BUILD_TYPERelease \ -DMYAWESOME_BUILD_SHAREDON \ -DMYAWESOME_BUILD_TESTSON cmake --build build -j 4 ctest --test-dir build cmake --install build --prefix D:/sdk/myawesome-DCMAKE_BUILD_TYPERelease只对 MinGW Makefiles 和 Ninja 这类单配置生成器有效VS 多配置生成器要用--config Release。-j 4是并行编译任务数MinGW Makefiles 生成器会对应展开成 mingw32-make 的并行参数。ctest --test-dir build会跑所有add_test()注册的测试。cmake --install配合--prefix把产物安装到 D:/sdk/myawesome之后其他项目想引用这个库直接find_package指向这个前缀。编译过程中最常看的文件是 build/CMakeCache.txt它记录了所有缓存变量。比如想看编译器路径findstr CMAKE_CXX_COMPILER: build\CMakeCache.txt如果配置阶段因为某个库找不到而失败第一次看这个文件就能确认到底是编译器选错、路径写错、还是某个依赖真的没装。4.4 用 CMake GUI 可视化调参命令行背不住参数的时候cmake-gui 是救命稻草。启动方式D:\tools\cmake-3.17.1-win64-x64\bin\cmake-gui.exe打开后操作流程固定四步顶部填源码目录和 build 目录。点 Configure弹出的对话框里选生成器MinGW 就选 MinGW Makefiles并指定编译器。中间列表会刷新出所有缓存变量新增变量用红色标出按需勾选或改值。点 Generate生成构建脚本再回到命令行执行cmake --build build。GUI 本质上是帮你拼命令行参数改完点 ConfigureCMakeCache.txt 就更新了。它和命令行操作混用没有冲突前提是你别在 GUI 里改完又跑命令行配置两边的增量参数有时会不一致。我个人习惯是 GUI 只用来查变量名最终构建还是命令行这样每条记录都能留在 shell 历史里。5. 避坑与排查PATH 不生效、编译器检测失败、Qt 配置找不到这章把我实际操作中踩过的坑整理出来按「现象 → 原因 → 解决」的方式写。每一条都是真实翻车记录不是从文档里抄的。5.1 PATH 不生效的三种情况现象终端里运行cmake --version提示「cmake 不是内部或外部命令」或者出来的是另一个旧版本。原因最常见三种。第一只在某个窗口里用过set PATH...窗口一关就没了新开的窗口自然找不到。第二用了setx后没有开新窗口直接在当前窗口里验证当前窗口读不到 setx 写入的新值。第三解压路径写错了比如把目录解压到了C:\Users\xxx\Downloads下面然后 PATH 里写的是另外的路径。解决先用完整路径确认 cmake.exe 存在dir D:\tools\cmake-3.17.1-win64-x64\bin\cmake.exe。然后重新开终端执行where cmake看实际命中哪个路径。如果where cmake的结果和你预期不符说明 PATH 里有多个候选把旧的删掉或者把新目录前置。5.2 CMake 配置报编译器检测失败failed to determine compiler id现象配置时出现The C compiler identification is unknown或者CMake Error at .../CMakeDetermineCompilerId.cmake:9这样的报错。这个错误在 Linux 上路径常是/usr/share/cmake-4.2/modules/...Windows 上则是 CMake 安装目录下的share/cmake-3.17/...本质是同一件事CMake 找不到可用的 C/C 编译器。原因你只装了 CMake没装编译器或者编译器装了但不在 PATH或者生成器和编译器不匹配。比如选了 Visual Studio 生成器但机器上根本没有 VS选了 MinGW Makefiles 但 PATH 里找不到 gcc。解决先确认编译器存在。MinGW 环境跑gcc --versionVS 环境打开「x64 Native Tools Command Prompt」跑cl。确认编译器没问题后删掉 build 目录重新配置。注意这里一定要删干净的 build 目录或者至少删掉 CMakeCache.txt因为缓存的编译器路径一旦写成错的后面反复配置都不会自动纠正。5.3 Qt 项目报 Qt5Config.cmake 找不到现象配置 Qt 项目时报错信息里出现CMake Error at C:/Qt/qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5/Qt5Config.cmake:94或者干脆Could not find a package configuration file provided by Qt5。原因CMake 找 Qt 依赖的是CMAKE_PREFIX_PATH或者环境变量CMAKE_PREFIX_PATH。报错里的路径如果指向一个不存在的旧版本多半是 build 目录的 CMakeCache.txt 里残留了上一次配置时写的 Qt 路径而那个路径对应版本已经卸载或移动了。解决删掉 build 目录重新配置或者直接删除 CMakeCache.txt。然后用命令行显式指定 Qt 路径cmake -S . -B build -G MinGW Makefiles \ -DCMAKE_PREFIX_PATHC:/Qt/Qt5.12.12/5.12.12/mingw73_64戴-D参数直传的优先级比 CMake 自己 find 的要高可以少走很多弯路。5.4 zip 解压不完整或杀软误删现象解压后 bin 目录里没有 cmake.exe或者双击 cmake-gui.exe 直接闪退报 0xc000007b 错误。原因zip 包在下载过程中损坏文件不完整或者杀毒软件把 cmake.exe 隔离了也有极小概率是解压工具对中文路径、文件名编码处理不当导致的半解压状态。很多人从网上下资源遇到「zip 伪加密」资源管理器解压到一半提示要密码实际上压缩包本身没有加密只是设置了伪加密标志7-Zip 可以直接绕过。解决重新下载一遍核对压缩包大小是否跟发布页一致。解压工具建议用 7-Zip 或者 Windows 自带的 tar别用某些国产压缩软件去解「伪加密」包。如果杀软误删去隔离区恢复并把目录加入信任白名单。解压完成后第一时间确认bin\cmake.exe存在。5.5 老版本 CMake 遇上新编译器VS 2022 检测失败现象用-G Visual Studio 17 2022配置时报生成器不可用或者配置过程中找不到 v143 工具集。原因cmake-3.17.1 是 2020 年的版本那时候 VS 2022 还没发布它的生成器列表里只有 Visual Studio 16 2019 及更早版本。CMake 对编译器版本的识别有明确上限老版本不认识新工具集这不是配置问题是版本边界。解决对这个包要么用 VS 2019 生成器要么先用 CMake 生成旧版本 VS 工程再用 VS 2022 打开升级。如果你想用 VS 2022 的完整支持就得换新版 CMake这不是免安装包能解决的是 CMake 版本和编译器版本的匹配问题。做老项目复现时我反而喜欢这种锁定关系——CMake 3.17.1 配 VS 2019行为是可预期的不会因为 CMake 升级带来新的解析差异。6. 验证安装与一条龙调试技巧从 where 到 --trace 的排错路径最后这章讲我每次拿到一个免安装工具包后的标准验证流程同时把 CMake 调试时最常用到的几个技巧串起来。第一步永远是验证路径和版本。新开一个终端执行三行where cmake cmake --version where gcc第一行确认命中路径第二行确认版本是 3.17.1第三行确认编译器在。如果第三行为空后边 CMake 配置必然失败这时候先装编译器别急着调试 CMakeLists。第二步是进 build 目录看缓存变量。很多所谓的「玄学报错」其实都能在 CMakeCache.txt 里找到答案cmake -LAH build | findstr CMAKE_CXX_COMPILER-LAH会把所有缓存变量按字母序打印出来findstr过滤出你关心的变量。看编译器路径、编译器 ID、构建类型一眼就能判断配置阶段到底发生了什么。第三步是追踪 CMakeLists.txt 里的变量。如果你在自己写 CMake 逻辑配置阶段经常不明不白用 trace 模式看 CMake 到底执行了什么cmake -S . -B build_trace --trace-expand 21 | findstr MYAWESOME--trace-expand会把每一行 CMakeLists 的变量展开后打印出来配合 findstr 过滤到项目自己的变量排查路径拼接、条件分支非常有效。第四步很多人不知道 3.17 这个版本不支持 CMakePresets.json。CMake Presets 是 3.19 才引入的功能这个包里没有。如果你想实现类似预设的效果最接近的替代方案是-C指定初始化缓存文件# mycache.cmake set(CMAKE_BUILD_TYPE Release CACHE STRING FORCE) set(MYAWESOME_BUILD_TESTS ON CACHE BOOL FORCE)配置时带上这个文件cmake -S . -B build -C mycache.cmake-C文件里的 set 会作为初始缓存值生效效果和命令行写-DCMAKE_BUILD_TYPERelease基本一致好处是可以把一组常用参数固化成文件提交到仓库里谁拉下来都能复现同一套配置不需要背命令。从那以后我每到一个新环境或者换一个新解压目录都会强制自己先跑一遍where cmake加cmake --version确认当前生效的是哪一个 CMake再继续手头的项目。这个习惯帮我少踩了很多「明明版本有问题还硬调 CMakeLists」的白用工时。希望帮到你。本文还有配套的精品资源点击获取