简介CMake 3.14.2 Windows 64位版是一款功能完备的跨平台自动化构建工具核心用途是根据CMakeLists.txt描述生成Visual Studio工程或Makefile避免手工维护复杂构建配置对需要整合OpenCV等第三方库、希望统一管理C/C项目构建流程的开发者尤其实用。压缩包共收录5681个文件大小29.58MB内容以帮助文档和配置脚本为主包含约1500余个txt文本、1500余个html网页、1500余个rst说明以及786个cmake构建脚本同时提供cmake、cmake-gui、ccmake可执行程序以及ctest、cpack测试与打包工具覆盖从工程生成到测试发布的主要环节。包内还保留了完整的man手册页面覆盖命令、属性、变量、模块等主题并附有示例项目既能帮助新手理解CMakeLists.txt写法也方便有经验者离线查考。已有170人学习下载适合作为Windows 64位环境下搭建OpenCV开发环境或维护跨平台自动化构建流程的离线工具包。1. 一个装错版本就能让构建链翻车的工具cmake-3.14.2-win64-x64 到底解决什么问题最近在某个老项目里折腾构建发现同事的机器上一律装的是 cmake-3.14.2-win64-x64 这个包新版本 CMake 装上去反而编不过。原因不是新版本不行而是项目里的 CMakeLists.txt 当时就是按 3.14 的语法和策略写的高版本默认启用的新策略把老写法判成了错误。所以搞清楚这个版本到底适合谁、怎么装、有哪些坑比盲目追求最新版实际得多。这篇文章会从 CMake 3.14.2 在 x64 Windows 下的定位讲起然后给出从解压、配 PATH 到生成、编译、排查的完整路径。适合下面几种人被旧项目锁定必须用 3.14 的维护者、在 Windows 上第一次配 CMake 的入门者、以及想在 CI 里固定 CMake 版本但不想折腾的工程师。如果你只需要一个能跑的 CMake直接跳到第 3 章如果你想知道为什么 3.14.2 还是主流建议从头看。2. 先搞清楚 CMake 3.14 与 Windows x64 的匹配关系再动手很多人习惯直接下载安装等踩坑了才回头看。这里我把两个最容易被忽略的问题拆开一是 3.14.2 这个版本号为什么值得锁二是 win64-x64 这个标签背后带着什么平台信息。这两件事不搞清楚后面配置生成器的时候大概率会做无用功。2.1 为什么是 3.14.2这个版本的特殊位置在哪里CMake 的版本号格式是主版本.次版本.补丁。3.14.2 是在 2019 年发布的第二个补丁版本修复了 3.14.0 里一批和 Windows、CUDA 相关的问题。对于 Windows 用户来说3.14 是第一个对 Visual Studio 2019 和 Ninja 支持已经相当成熟的版本同时它的cmake --build、-S/-B参数、CMAKE_GENERATOR_PLATFORM等今天常用的开关都已经稳定。很多开源项目在 README 里写的最低版本就是 3.14不是因为新版本不支持而是因为老项目不想承担高版本策略变化带来的重构成本。比如cmake_minimum_required(VERSION 3.14)会启用对应 3.14 的策略设置如果你用 3.20 编译同一个项目CMake 会提示某些已经不推荐的行为甚至直接 FATAL_ERROR。所以 CMake 的老版本并不是「过时的垃圾」而是被项目环境锁定了。另外3.14.2 是官方发布的稳定预编译版不需要自己从源码构建。对于 Windows x64官方提供了 zip 和 exe 两种包下面一节会详细说怎么选。如果你正在维护的模拟项目X要求最低版本是 3.14那用 3.14.2 这个补丁版本是最稳妥的选择因为它比 3.14.0 修了更多边角问题又不会引入 3.15 之后的破坏性策略。2.2 win64-x64 到底指什么编译器、生成器与平台三元组win64-x64不是「只能生成 x64 程序」的意思。它指的是 CMake 这个可执行文件本身是 64 位 Windows 程序并且默认按 64 位 Windows 环境来搜索工具链。至于生成出来的项目是 32 位还是 64 位取决于你指定的生成器generator和平台参数也就是-G Visual Studio 17 2022 -A x64里的-A或者 Ninja 下的CMAKE_GENERATOR_PLATFORM。这里有一个常见的认知误区装了 x64 版 CMake然后用 Visual Studio 生成器构建如果不加-AVS 生成器默认可能选 Win32。很多人的「我明明装了 x64 包为什么 exe 是 32 位」就是这么来的。CMake 本身的位数只影响解析脚本的性能不影响目标程序位数。组件位数来源说明CMake 程序win64-x64只影响 CMake 自身运行效率生成器选择的编译器套件VS 或 MinGW/Ninja 决定目标 exe-A参数或CMAKE_GENERATOR_PLATFORM常见为 x64 / Win32可以用一个命令确认当前系统架构在 PowerShell 里运行echo $env:PROCESSOR_ARCHITECTURE输出 AMD64 就说明系统是 64 位。这个命令与 CMake 无关但能帮你确认环境避免后面构建时怀疑 CMake 位数。另一个更接近 CMake 的验证方式是读取缓存变量配置完成后执行cmake -LA -N build在输出里找CMAKE_GENERATOR_PLATFORM如果该变量为空或没有写 x64说明生成器默认平台不一定是你要的 64 位。2.3 安装包选择zip 还是 exe安装版与免安装版的取舍cmake-3.14.2-win64-x64 这个名字对应的是 zip 包而不是 exe。官方下载目录里通常会同时提供 zip 和 msi/exe 两种形式。zip 是绿色版解压即用不需要安装向导也不会往注册表里写东西exe 是交互式安装会注册 CMake GUI 的关联菜单还会建议写入系统 PATH。我的选择习惯是个人开发机用 exe因为省事CI 服务器或者需要精确控制版本的构建机用 zip因为可以随便解压到任意目录用完整路径调用不污染全局环境。zip 还有一个好处就是可以在一个机器上同时放多个版本切换时只需要改 PATH 顺序。对比点zip 免安装版exe 安装版管理员权限不需要通常需要写入 PATH手动向导可选多版本共存方便不方便GUI 菜单没有可手动创建自动关联如果你在 CI 里用脚本控制zip 是唯一合理的选项。下载 zip 后建议先做哈希校验再解压避免压缩包损坏导致运行时报莫名的 DLL 缺失。校验命令在 PowerShell 里是这样# 计算下载包的 SHA256与官方发布页面公布的值对比 Get-FileHash -Path $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -Algorithm SHA256注意哈希只是验证文件完整性的手段不是逃避下载问题的万能药。如果哈希对不上大概率是下载中断或镜像不一致重新下载一次通常能解决。下面第 3 章就围绕 zip 包展开因为它的步骤更通用exe 安装只需要一路 Next 反而没什么好讲的。3. 在 Windows 上装好 cmake-3.14.2-win64-x64完整步骤这一章开始动手。我会用 PowerShell 命令作为主操作路径因为现在 Windows 10/11 上 PowerShell 已经是默认终端。如果你习惯 cmd大部分命令还需要额外改一下但核心的 CMake 指令是一致的。3.1 下载、解压与目录规划先从官方下载站点获取 zip 包。注意文件名一定是cmake-3.14.2-win64-x64.zip如果你下到了win32或x86先回头看看是不是点错入口。下载完成后用 PowerShell 直接解压。我建议把版本号留在目标目录里方便以后识别但不要留空格。# 解压 CMake zip 包到 C:\Tools 下保留版本目录 Expand-Archive -Path $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -DestinationPath C:\Tools上面命令执行后你会得到C:\Tools\cmake-3.14.2-win64-x64这样的目录结构C:\Tools\cmake-3.14.2-win64-x64 ├─ bin │ ├─ cmake.exe │ ├─ cmake-gui.exe │ ├─ ctest.exe │ └─ cpack.exe ├─ share └─ docbin目录下的cmake.exe就是命令行工具。如果你要使用ctest和cpack它们也在同一个目录里。后面配 PATH 也是指到bin不是指到根目录。如果你的 Windows 版本较新也可以直接用系统自带的 tar 命令解压不过它的输出不会像Expand-Archive那样显式创建一层目录我一般还是会用Expand-Archive。桑心的是Expand-Archive在解压路径包含非英文或较长的目录时偶尔会报错此时改用# 用 Windows 10 自带的 tar 解压 zip-C 指定目标目录 tar -xf $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -C C:\Tools无论哪种方式解压后先看一眼bin\cmake.exe是否存在。如果解压失败但没报错很可能是下载的文件不是完整的 zip回到刚才的哈希校验步骤。3.2 把 CMake 加入 PATH用户级还是系统级配置 PATH 涉及到作用范围和安全性。我一般建议个人开发机上用用户级 PATH因为不需要管理员权限CI 服务器上不建议把 CMake 放进系统 PATH而是直接在构建脚本里写完整路径C:\Tools\cmake-3.14.2-win64-x64\bin\cmake.exe这样即使机器上装了别的版本也不会被 PATH 顺序影响到。在 PowerShell 里把 CMake 路径追加到用户 PATH 可以这样写# 读取当前用户 PATH追加 CMake bin 目录写回用户级环境变量 $oldPath [Environment]::GetEnvironmentVariable(Path, User) $newPath $oldPath ;C:\Tools\cmake-3.14.2-win64-x64\bin [Environment]::SetEnvironmentVariable(Path, $newPath, User)执行结束后新开的终端不会立刻生效你需要重启终端窗口或者在当前终端里手动刷新 PATH# 在当前进程刷新 PATH方便立即验证 $env:Path [Environment]::GetEnvironmentVariable(Path, User) ; [Environment]::GetEnvironmentVariable(Path, Machine)注意这里我没有用setx。setx有个坑它会把完整 PATH 变量截断到 1024 个字符如果你原有的 PATH 已经很长后面那些目录就消失了。用上面 .NET 的SetEnvironmentVariable方法不会截断但如果 PATH 里已经有同一路径执行两次会重复追加所以脚本化之前最好先做一次去重检查# 检查 CMake bin 是否已经在用户 PATH 中 $oldPath -split ; | Where-Object { $_ -eq C:\Tools\cmake-3.14.2-win64-x64\bin }如果返回空再执行追加否则跳过。如果你不喜欢命令行也可以用「编辑系统环境变量」对话框在「用户变量」的 Path 里新建一条填C:\Tools\cmake-3.14.2-win64-x64\bin。注意只填 bin 这一级别把整个目录填进去否则cmake.exe还是找不到。3.3 验证安装命令行、GUI 与 CMakeLists.txt 最小工程PATH 配好后首先要验证的自然是版本。新开一个终端执行cmake --version如果你看到cmake version 3.14.2那恭喜PATH 生效了。如果显示的是别的版本执行where.exe cmake看它指向哪里很可能是以前安装的版本在系统 PATH 里优先级更高。这个问题的排查在第 5 章会详细展开。版本号只能证明 CMake 能跑不能证明它和编译器能正常协作。我建议紧接着做一次真实构建验证。先建一个最小工程# 创建测试目录和 CMakeLists.txt New-Item -ItemType Directory -Path C:\tmp\cmake-test -Force Set-Content -Path C:\tmp\cmake-test\CMakeLists.txt -Value cmake_minimum_required(VERSION 3.14) project(cmake_test C CXX) add_executable(sample main.c) Set-Content -Path C:\tmp\cmake-test\main.c -Value #include stdio.h int main(void){ printf(cmake ok\n); return 0; } 然后进入目录执行配置和构建。如果你用的是 Visual Studio可以直接用 VS 生成器cd C:\tmp\cmake-test cmake -S . -B build -G Visual Studio 16 2019 -A x64 cmake --build build --config Release如果这两条命令没有报错并且build\Release\cmake_test.exe出现了说明安装链路是通的。如果你的机器上没有 VS也可以先装 MinGW-w64然后用-G MinGW Makefiles生成后面第 4 章会讲各种生成器的差异。这里我还习惯顺手开一下cmake-gui.exe确认 GUI 界面能正常启动。虽然大多数操作在命令行完成但 GUI 的「Configure」按钮能暴露很多命令行下不易察觉的缓存问题尤其是在手动改过 CMakeCache.txt 之后GUI 里能直接看到有没有报错。4. 用 CMake 3.14 构建一个真实项目从 CMakeLists.txt 到可执行文件上一章的最小工程只做了最简单的事但实际项目里几乎都会用到库、头文件目录、链接参数。这一章用一个稍完整的例子覆盖 CMake 3.14 最常用的目标相关指令。4.1 一个能跑的最小 CMakeLists.txt我们建一个包含静态库和可执行程序的项目目录结构如下cmake-sample/ ├─ CMakeLists.txt ├─ include/ │ └─ sample.h ├─ src/ │ └─ sample.c └─ main/ └─ main.c三个源码文件的内容很简单。sample.h声明一个函数sample.c实现它main.c调用它// include/sample.h #ifndef SAMPLE_H #define SAMPLE_H int add(int a, int b); #endif// src/sample.c #include sample.h int add(int a, int b) { return a b; }// main/main.c #include stdio.h #include sample.h int main(void) { printf(2 3 %d\n, add(2, 3)); return 0; }对应的CMakeLists.txt这样写cmake_minimum_required(VERSION 3.14) project(cmake_sample C CXX) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) add_library(sample STATIC src/sample.c) target_include_directories(sample PUBLIC include) add_executable(sample_app main/main.c) target_link_libraries(sample_app PRIVATE sample)这里我用了add_library生成静态库再用target_link_libraries链接到可执行文件。target_include_directories使用PUBLIC传播头文件路径这样main.c里#include sample.h能直接找到。set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ...)把 exe 统一放到bin目录避免 Debug/Release 各生成一个目录导致找不到产物。对于 3.14.2上面这些命令都是稳定可用的。注意我没有写add_definitions或include_directories因为那俩是老式写法target_*命令在维护性和依赖传递上更安全。3.14 对这个模型的命令支持已经很完善不需要用任何新版本特性。4.2 指定生成器与平台参数-G、-A、--build 的使用配置项目时除了-S和-B最常用的是-G指定生成器。在 Windows x64 上常见生成器有两类Visual Studio 生成器Visual Studio 16 2019等多配置平台通过-A x64指定。Ninja 或 MinGW Makefiles单配置需要在 CMake 命令里指定CMAKE_BUILD_TYPE平台通过环境变量或CMAKE_GENERATOR_PLATFORM指定。用 VS 生成器构建这个项目的完整命令cmake -S . -B build-vs -G Visual Studio 16 2019 -A x64 cmake --build build-vs --config Release用 Ninja 构建的命令前提是已经安装了 Ninja且编译器路径可用cmake -S . -B build-ninja -G Ninja -DCMAKE_BUILD_TYPERelease cmake --build build-ninja注意-A参数只在 Visual Studio 生成器下有效。如果你用-G Ninja又写了-A x64CMake 会报错说-A不适用于该生成器。这是刚开始经常翻车的地方。--build参数是 3.14 里的成熟功能它的意义在于不必手动去调用底层构建工具。CMake 会根据缓存的生成器自动调对应的工具。你可以用--parallel N控制并行度比如cmake --build build-vs --config Release --parallel 4在 Ninja 上效果明显在 VS 上会传到 MSBuild 的/m参数。4.3 配置 Debug/Release 与多配置生成器的坑这一节讲清楚CMAKE_BUILD_TYPE和--config的区别。上文的 Ninja 是单配置生成器CMake 在生成时就要确定CMAKE_BUILD_TYPE之后如果要换 Debug需要重新创建一个构建目录。Visual Studio 是多配置生成器一个 build 目录同时包含 Debug、Release 等多个配置构建时通过--config选择不需要重新配置。如果你用 VS 生成器但在命令行里加了-DCMAKE_BUILD_TYPERelease会发现它被忽略了因为多配置生成器不吃这个变量。反过来说如果你用 Ninja在构建时加--config Release也会报错因为该生成器没有这个选项。理解这一点能帮你少踩很多坑。另一个坑是当你在同一个构建目录里从 VS 生成器切换到 Ninja 时CMakeCache.txt 里还残留着原来的CMAKE_GENERATORCMake 会直接报错。正确做法是删除整个build目录重新配置。我习惯把它写成一个脚本# 清理并重新配置 VS x64 rm -rf build cmake -S . -B build -G Visual Studio 16 2019 -A x64 cmake --build build --config Release在 PowerShell 里rm -rf build可以运行但更标准的是Remove-Item -Recurse -Force build。如果你在 CI 脚本里这一步尤为重要否则缓存会让构建结果变得「玄学」。有时你已经删掉了 build 目录但 CMake 还会报错那是因为你手误删的是build-vs而不是build脚本里变量用错这种低级错误我犯过不止一次。5. 排坑3.14.2 常见翻车现场与排查路径这一章我们集中解决 CMake 3.14.2 在 x64 Windows 下最常遇到的几个问题。每一条我都按「现象 → 原因 → 解决」的顺序来写方便你对照排查。5.1 现象一CMakeLists.txt 解析时报未知命令或策略错误现象运行cmake -S . -B build后输出CMake Error at CMakeLists.txt:XX (add_subdirectory): Unknown CMake command add_subdirectory或者CMake 3.14.2 is lower than required. CMake 3.20 required这类信息。原因前一种通常不是add_subdirectory不存在而是因为该命令来自某个模块而你没include()或者命令拼写有误。后一种明确是版本不满足。也有一种情况项目用到了 3.14 之后加入的语法或策略比如cmake_path()是 3.20 的。解决先看cmake_minimum_required是否小于 3.14。如果项目要求高于 3.14你就需要换新版 CMake而不是继续在 3.14 上挣扎。如果项目要求是 3.14 以下却报了未知命令检查命令拼写如果命令来自某个.cmake模块确认include()是否写在前面。举个例子include(CTest)后才有enable_testing()相关功能顺序错了一样会报错。5.2 现象二生成的 exe 是 32 位而我以为 win64-x64 一定是 64 位现象构建完打开任务管理器看进程架构或者用工具查看 PE 头显示 x86。原因CMake 包的位数是 x64但生成目标平台由生成器决定。Visual Studio 生成器如果不加-A x64默认平台可能是 Win32。Ninja/MinGW 环境下默认取决于编译器本身如果你用的是 32 位 MinGW那自然生成 32 位。解决重新配置时显式指定平台。VS 生成器加-A x64Ninja 加-DCMAKE_GENERATOR_PLATFORMx64。然后在 CMakeCache.txt 里确认CMAKE_GENERATOR_PLATFORM的值是空还是 x64。如果缓存里已经写错删除 build 目录重新配置。5.3 现象三使用 Ninja 生成器时提示找不到编译器 cl现象cmake -G Ninja -DCMAKE_BUILD_TYPERelease ..在 Visual Studio 环境下执行报错CMAKE_C_COMPILER not found或者The C compiler cl.exe is not able to compile a simple test program。原因Ninja 只是一个构建调度工具它不提供编译器。你必须在一个能调用cl.exe的环境中运行 CMake也就是先执行了vcvars64.bat或者使用「适用于 VS 的开发人员命令提示符」。很多人直接在普通 PowerShell 里运行 Ninja 生成器自然找不到 MSVC。解决要么改用 Visual Studio 生成器让 CMake 自己找 MSVC要么每次构建前先运行vcvars64.bat再在同一个终端里执行 CMake。这个坑的本质是混淆了「构建工具」和「编译器工具链」的职责。5.4 现象四同时装了多个 CMake 版本命令行调用的不是 3.14.2现象cmake --version输出一个别的高版本或者明明刚配好 PATHwhere cmake显示旧路径。原因系统 PATH 里的顺序比用户 PATH 更靠前或者旧版本的目录还残留在 PATH 中。Windows 命令搜索按 PATH 顺序进行先找到哪个就用哪个。解决在 PowerShell 里执行where.exe cmake看匹配顺序。然后调整 PATH让C:\Tools\cmake-3.14.2-win64-x64\bin出现在更靠前的位置。如果你不希望改动全局 PATH可以直接用完整路径调用比如在 CI 脚本里把cmake变量指向完整路径。这是最可控的方式。注意3.14.2 的 CMake 缓存文件夹名包含了版本号当你切换版本时旧 build 目录的 CMakeCache.txt 记录的是旧版路径直接复用会报错所以切换版本后最好删掉 build 目录重配。5.5 现象五配置成功构建时却报链接器找不到标准库现象cmake --build build在链接一步报错比如LINK : fatal error LNK1104: cannot open file libcmt.lib。原因CMake 配置时代码生成和编译器路径检查通过了但链接阶段找不到 MSVC 的标准运行库。常见于你混合使用了不同版本的 VS 工具集或者在普通命令行里调用cmake --build导致链接器环境变量被清掉了。解决用完整 VS 开发环境执行构建。最稳妥的是从「开始菜单」打开「x64 Native Tools Command Prompt for VS 2019」然后在这个终端里执行cmake --build。如果必须在 CI 里自动化可以在脚本开头调用 VS 自带的vcvars64.bat。注意路径里的具体目录如果用了不同版本请对应修改。6. 我常用的 3.14.2 验证与清理技巧版本锁定之后日常工作中最耗时间的不是写 CMakeLists.txt而是排查「明明改了 CMakeLists 却没生效」「缓存里不知道存了什么」这类问题。下面三个小技巧是我在多个项目里反复用到的。6.1 用 cmake -LAH 快速审查缓存变量cmake -LAH -S . -B build会列出当前构建目录里的所有缓存变量包括CMAKE_GENERATOR、CMAKE_GENERATOR_PLATFORM、CMAKE_BUILD_TYPE、CMAKE_PREFIX_PATH等。它比打开 CMakeCache.txt 更人性化因为会过滤掉内部变量。排查生成器选错、平台类型不对时我第一件事就是跑这个命令。6.2 用 --trace-source 定位 CMakeLists.txt 的解析问题cmake --trace-sourceCMakeLists.txt -S . -B build会逐行打印脚本执行的函数调用。如果你在条件分支里写错if或者foreach很容易通过 trace 看到执行路径。3.14 对 trace 的支持已经很稳定不需要换新版。遇到「为什么这个 message 没打印」类似的问题加上 trace 跑一遍基本能找到答案。6.3 清理缓存删 build 目录比改缓存快得多很多所谓「玄学」问题本质是 CMakeCache.txt 里的路径或生成器残留。换编译器、换版本、换目录位置之后最省心的做法是直接删除 build 目录重新配置。我的习惯是保留一个clean.ps1脚本# 删掉所有构建目录保留源文件 Remove-Item -Recurse -Force build* -ErrorAction SilentlyContinue注意build*会把build-vs、build-ninja等一并删掉。然后重新配置时先确认 PATH 里的 CMake 是 3.14.2再跑cmake -S . -B build -G ...。我之前在一台机器上同时装了 3.14.2 和 3.20结果where cmake指向了 3.20项目用的旧语法直接报错。后来我习惯在每个项目目录下放一个tools文件夹把对应版本的 CMake 解压进去然后用tools\cmake\bin\cmake.exe这种完整路径来构建再也没出现过「版本玄学」。希望这个习惯也能帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/15 18:06:31 · 阅读 1.2k CMake 3.14.2 win64-x64 Windows 安装与排坑指南
简介CMake 3.14.2 Windows 64位版是一款功能完备的跨平台自动化构建工具核心用途是根据CMakeLists.txt描述生成Visual Studio工程或Makefile避免手工维护复杂构建配置对需要整合OpenCV等第三方库、希望统一管理C/C项目构建流程的开发者尤其实用。压缩包共收录5681个文件大小29.58MB内容以帮助文档和配置脚本为主包含约1500余个txt文本、1500余个html网页、1500余个rst说明以及786个cmake构建脚本同时提供cmake、cmake-gui、ccmake可执行程序以及ctest、cpack测试与打包工具覆盖从工程生成到测试发布的主要环节。包内还保留了完整的man手册页面覆盖命令、属性、变量、模块等主题并附有示例项目既能帮助新手理解CMakeLists.txt写法也方便有经验者离线查考。已有170人学习下载适合作为Windows 64位环境下搭建OpenCV开发环境或维护跨平台自动化构建流程的离线工具包。1. 一个装错版本就能让构建链翻车的工具cmake-3.14.2-win64-x64 到底解决什么问题最近在某个老项目里折腾构建发现同事的机器上一律装的是 cmake-3.14.2-win64-x64 这个包新版本 CMake 装上去反而编不过。原因不是新版本不行而是项目里的 CMakeLists.txt 当时就是按 3.14 的语法和策略写的高版本默认启用的新策略把老写法判成了错误。所以搞清楚这个版本到底适合谁、怎么装、有哪些坑比盲目追求最新版实际得多。这篇文章会从 CMake 3.14.2 在 x64 Windows 下的定位讲起然后给出从解压、配 PATH 到生成、编译、排查的完整路径。适合下面几种人被旧项目锁定必须用 3.14 的维护者、在 Windows 上第一次配 CMake 的入门者、以及想在 CI 里固定 CMake 版本但不想折腾的工程师。如果你只需要一个能跑的 CMake直接跳到第 3 章如果你想知道为什么 3.14.2 还是主流建议从头看。2. 先搞清楚 CMake 3.14 与 Windows x64 的匹配关系再动手很多人习惯直接下载安装等踩坑了才回头看。这里我把两个最容易被忽略的问题拆开一是 3.14.2 这个版本号为什么值得锁二是 win64-x64 这个标签背后带着什么平台信息。这两件事不搞清楚后面配置生成器的时候大概率会做无用功。2.1 为什么是 3.14.2这个版本的特殊位置在哪里CMake 的版本号格式是主版本.次版本.补丁。3.14.2 是在 2019 年发布的第二个补丁版本修复了 3.14.0 里一批和 Windows、CUDA 相关的问题。对于 Windows 用户来说3.14 是第一个对 Visual Studio 2019 和 Ninja 支持已经相当成熟的版本同时它的cmake --build、-S/-B参数、CMAKE_GENERATOR_PLATFORM等今天常用的开关都已经稳定。很多开源项目在 README 里写的最低版本就是 3.14不是因为新版本不支持而是因为老项目不想承担高版本策略变化带来的重构成本。比如cmake_minimum_required(VERSION 3.14)会启用对应 3.14 的策略设置如果你用 3.20 编译同一个项目CMake 会提示某些已经不推荐的行为甚至直接 FATAL_ERROR。所以 CMake 的老版本并不是「过时的垃圾」而是被项目环境锁定了。另外3.14.2 是官方发布的稳定预编译版不需要自己从源码构建。对于 Windows x64官方提供了 zip 和 exe 两种包下面一节会详细说怎么选。如果你正在维护的模拟项目X要求最低版本是 3.14那用 3.14.2 这个补丁版本是最稳妥的选择因为它比 3.14.0 修了更多边角问题又不会引入 3.15 之后的破坏性策略。2.2 win64-x64 到底指什么编译器、生成器与平台三元组win64-x64不是「只能生成 x64 程序」的意思。它指的是 CMake 这个可执行文件本身是 64 位 Windows 程序并且默认按 64 位 Windows 环境来搜索工具链。至于生成出来的项目是 32 位还是 64 位取决于你指定的生成器generator和平台参数也就是-G Visual Studio 17 2022 -A x64里的-A或者 Ninja 下的CMAKE_GENERATOR_PLATFORM。这里有一个常见的认知误区装了 x64 版 CMake然后用 Visual Studio 生成器构建如果不加-AVS 生成器默认可能选 Win32。很多人的「我明明装了 x64 包为什么 exe 是 32 位」就是这么来的。CMake 本身的位数只影响解析脚本的性能不影响目标程序位数。组件位数来源说明CMake 程序win64-x64只影响 CMake 自身运行效率生成器选择的编译器套件VS 或 MinGW/Ninja 决定目标 exe-A参数或CMAKE_GENERATOR_PLATFORM常见为 x64 / Win32可以用一个命令确认当前系统架构在 PowerShell 里运行echo $env:PROCESSOR_ARCHITECTURE输出 AMD64 就说明系统是 64 位。这个命令与 CMake 无关但能帮你确认环境避免后面构建时怀疑 CMake 位数。另一个更接近 CMake 的验证方式是读取缓存变量配置完成后执行cmake -LA -N build在输出里找CMAKE_GENERATOR_PLATFORM如果该变量为空或没有写 x64说明生成器默认平台不一定是你要的 64 位。2.3 安装包选择zip 还是 exe安装版与免安装版的取舍cmake-3.14.2-win64-x64 这个名字对应的是 zip 包而不是 exe。官方下载目录里通常会同时提供 zip 和 msi/exe 两种形式。zip 是绿色版解压即用不需要安装向导也不会往注册表里写东西exe 是交互式安装会注册 CMake GUI 的关联菜单还会建议写入系统 PATH。我的选择习惯是个人开发机用 exe因为省事CI 服务器或者需要精确控制版本的构建机用 zip因为可以随便解压到任意目录用完整路径调用不污染全局环境。zip 还有一个好处就是可以在一个机器上同时放多个版本切换时只需要改 PATH 顺序。对比点zip 免安装版exe 安装版管理员权限不需要通常需要写入 PATH手动向导可选多版本共存方便不方便GUI 菜单没有可手动创建自动关联如果你在 CI 里用脚本控制zip 是唯一合理的选项。下载 zip 后建议先做哈希校验再解压避免压缩包损坏导致运行时报莫名的 DLL 缺失。校验命令在 PowerShell 里是这样# 计算下载包的 SHA256与官方发布页面公布的值对比 Get-FileHash -Path $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -Algorithm SHA256注意哈希只是验证文件完整性的手段不是逃避下载问题的万能药。如果哈希对不上大概率是下载中断或镜像不一致重新下载一次通常能解决。下面第 3 章就围绕 zip 包展开因为它的步骤更通用exe 安装只需要一路 Next 反而没什么好讲的。3. 在 Windows 上装好 cmake-3.14.2-win64-x64完整步骤这一章开始动手。我会用 PowerShell 命令作为主操作路径因为现在 Windows 10/11 上 PowerShell 已经是默认终端。如果你习惯 cmd大部分命令还需要额外改一下但核心的 CMake 指令是一致的。3.1 下载、解压与目录规划先从官方下载站点获取 zip 包。注意文件名一定是cmake-3.14.2-win64-x64.zip如果你下到了win32或x86先回头看看是不是点错入口。下载完成后用 PowerShell 直接解压。我建议把版本号留在目标目录里方便以后识别但不要留空格。# 解压 CMake zip 包到 C:\Tools 下保留版本目录 Expand-Archive -Path $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -DestinationPath C:\Tools上面命令执行后你会得到C:\Tools\cmake-3.14.2-win64-x64这样的目录结构C:\Tools\cmake-3.14.2-win64-x64 ├─ bin │ ├─ cmake.exe │ ├─ cmake-gui.exe │ ├─ ctest.exe │ └─ cpack.exe ├─ share └─ docbin目录下的cmake.exe就是命令行工具。如果你要使用ctest和cpack它们也在同一个目录里。后面配 PATH 也是指到bin不是指到根目录。如果你的 Windows 版本较新也可以直接用系统自带的 tar 命令解压不过它的输出不会像Expand-Archive那样显式创建一层目录我一般还是会用Expand-Archive。桑心的是Expand-Archive在解压路径包含非英文或较长的目录时偶尔会报错此时改用# 用 Windows 10 自带的 tar 解压 zip-C 指定目标目录 tar -xf $env:USERPROFILE\Downloads\cmake-3.14.2-win64-x64.zip -C C:\Tools无论哪种方式解压后先看一眼bin\cmake.exe是否存在。如果解压失败但没报错很可能是下载的文件不是完整的 zip回到刚才的哈希校验步骤。3.2 把 CMake 加入 PATH用户级还是系统级配置 PATH 涉及到作用范围和安全性。我一般建议个人开发机上用用户级 PATH因为不需要管理员权限CI 服务器上不建议把 CMake 放进系统 PATH而是直接在构建脚本里写完整路径C:\Tools\cmake-3.14.2-win64-x64\bin\cmake.exe这样即使机器上装了别的版本也不会被 PATH 顺序影响到。在 PowerShell 里把 CMake 路径追加到用户 PATH 可以这样写# 读取当前用户 PATH追加 CMake bin 目录写回用户级环境变量 $oldPath [Environment]::GetEnvironmentVariable(Path, User) $newPath $oldPath ;C:\Tools\cmake-3.14.2-win64-x64\bin [Environment]::SetEnvironmentVariable(Path, $newPath, User)执行结束后新开的终端不会立刻生效你需要重启终端窗口或者在当前终端里手动刷新 PATH# 在当前进程刷新 PATH方便立即验证 $env:Path [Environment]::GetEnvironmentVariable(Path, User) ; [Environment]::GetEnvironmentVariable(Path, Machine)注意这里我没有用setx。setx有个坑它会把完整 PATH 变量截断到 1024 个字符如果你原有的 PATH 已经很长后面那些目录就消失了。用上面 .NET 的SetEnvironmentVariable方法不会截断但如果 PATH 里已经有同一路径执行两次会重复追加所以脚本化之前最好先做一次去重检查# 检查 CMake bin 是否已经在用户 PATH 中 $oldPath -split ; | Where-Object { $_ -eq C:\Tools\cmake-3.14.2-win64-x64\bin }如果返回空再执行追加否则跳过。如果你不喜欢命令行也可以用「编辑系统环境变量」对话框在「用户变量」的 Path 里新建一条填C:\Tools\cmake-3.14.2-win64-x64\bin。注意只填 bin 这一级别把整个目录填进去否则cmake.exe还是找不到。3.3 验证安装命令行、GUI 与 CMakeLists.txt 最小工程PATH 配好后首先要验证的自然是版本。新开一个终端执行cmake --version如果你看到cmake version 3.14.2那恭喜PATH 生效了。如果显示的是别的版本执行where.exe cmake看它指向哪里很可能是以前安装的版本在系统 PATH 里优先级更高。这个问题的排查在第 5 章会详细展开。版本号只能证明 CMake 能跑不能证明它和编译器能正常协作。我建议紧接着做一次真实构建验证。先建一个最小工程# 创建测试目录和 CMakeLists.txt New-Item -ItemType Directory -Path C:\tmp\cmake-test -Force Set-Content -Path C:\tmp\cmake-test\CMakeLists.txt -Value cmake_minimum_required(VERSION 3.14) project(cmake_test C CXX) add_executable(sample main.c) Set-Content -Path C:\tmp\cmake-test\main.c -Value #include stdio.h int main(void){ printf(cmake ok\n); return 0; } 然后进入目录执行配置和构建。如果你用的是 Visual Studio可以直接用 VS 生成器cd C:\tmp\cmake-test cmake -S . -B build -G Visual Studio 16 2019 -A x64 cmake --build build --config Release如果这两条命令没有报错并且build\Release\cmake_test.exe出现了说明安装链路是通的。如果你的机器上没有 VS也可以先装 MinGW-w64然后用-G MinGW Makefiles生成后面第 4 章会讲各种生成器的差异。这里我还习惯顺手开一下cmake-gui.exe确认 GUI 界面能正常启动。虽然大多数操作在命令行完成但 GUI 的「Configure」按钮能暴露很多命令行下不易察觉的缓存问题尤其是在手动改过 CMakeCache.txt 之后GUI 里能直接看到有没有报错。4. 用 CMake 3.14 构建一个真实项目从 CMakeLists.txt 到可执行文件上一章的最小工程只做了最简单的事但实际项目里几乎都会用到库、头文件目录、链接参数。这一章用一个稍完整的例子覆盖 CMake 3.14 最常用的目标相关指令。4.1 一个能跑的最小 CMakeLists.txt我们建一个包含静态库和可执行程序的项目目录结构如下cmake-sample/ ├─ CMakeLists.txt ├─ include/ │ └─ sample.h ├─ src/ │ └─ sample.c └─ main/ └─ main.c三个源码文件的内容很简单。sample.h声明一个函数sample.c实现它main.c调用它// include/sample.h #ifndef SAMPLE_H #define SAMPLE_H int add(int a, int b); #endif// src/sample.c #include sample.h int add(int a, int b) { return a b; }// main/main.c #include stdio.h #include sample.h int main(void) { printf(2 3 %d\n, add(2, 3)); return 0; }对应的CMakeLists.txt这样写cmake_minimum_required(VERSION 3.14) project(cmake_sample C CXX) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) add_library(sample STATIC src/sample.c) target_include_directories(sample PUBLIC include) add_executable(sample_app main/main.c) target_link_libraries(sample_app PRIVATE sample)这里我用了add_library生成静态库再用target_link_libraries链接到可执行文件。target_include_directories使用PUBLIC传播头文件路径这样main.c里#include sample.h能直接找到。set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ...)把 exe 统一放到bin目录避免 Debug/Release 各生成一个目录导致找不到产物。对于 3.14.2上面这些命令都是稳定可用的。注意我没有写add_definitions或include_directories因为那俩是老式写法target_*命令在维护性和依赖传递上更安全。3.14 对这个模型的命令支持已经很完善不需要用任何新版本特性。4.2 指定生成器与平台参数-G、-A、--build 的使用配置项目时除了-S和-B最常用的是-G指定生成器。在 Windows x64 上常见生成器有两类Visual Studio 生成器Visual Studio 16 2019等多配置平台通过-A x64指定。Ninja 或 MinGW Makefiles单配置需要在 CMake 命令里指定CMAKE_BUILD_TYPE平台通过环境变量或CMAKE_GENERATOR_PLATFORM指定。用 VS 生成器构建这个项目的完整命令cmake -S . -B build-vs -G Visual Studio 16 2019 -A x64 cmake --build build-vs --config Release用 Ninja 构建的命令前提是已经安装了 Ninja且编译器路径可用cmake -S . -B build-ninja -G Ninja -DCMAKE_BUILD_TYPERelease cmake --build build-ninja注意-A参数只在 Visual Studio 生成器下有效。如果你用-G Ninja又写了-A x64CMake 会报错说-A不适用于该生成器。这是刚开始经常翻车的地方。--build参数是 3.14 里的成熟功能它的意义在于不必手动去调用底层构建工具。CMake 会根据缓存的生成器自动调对应的工具。你可以用--parallel N控制并行度比如cmake --build build-vs --config Release --parallel 4在 Ninja 上效果明显在 VS 上会传到 MSBuild 的/m参数。4.3 配置 Debug/Release 与多配置生成器的坑这一节讲清楚CMAKE_BUILD_TYPE和--config的区别。上文的 Ninja 是单配置生成器CMake 在生成时就要确定CMAKE_BUILD_TYPE之后如果要换 Debug需要重新创建一个构建目录。Visual Studio 是多配置生成器一个 build 目录同时包含 Debug、Release 等多个配置构建时通过--config选择不需要重新配置。如果你用 VS 生成器但在命令行里加了-DCMAKE_BUILD_TYPERelease会发现它被忽略了因为多配置生成器不吃这个变量。反过来说如果你用 Ninja在构建时加--config Release也会报错因为该生成器没有这个选项。理解这一点能帮你少踩很多坑。另一个坑是当你在同一个构建目录里从 VS 生成器切换到 Ninja 时CMakeCache.txt 里还残留着原来的CMAKE_GENERATORCMake 会直接报错。正确做法是删除整个build目录重新配置。我习惯把它写成一个脚本# 清理并重新配置 VS x64 rm -rf build cmake -S . -B build -G Visual Studio 16 2019 -A x64 cmake --build build --config Release在 PowerShell 里rm -rf build可以运行但更标准的是Remove-Item -Recurse -Force build。如果你在 CI 脚本里这一步尤为重要否则缓存会让构建结果变得「玄学」。有时你已经删掉了 build 目录但 CMake 还会报错那是因为你手误删的是build-vs而不是build脚本里变量用错这种低级错误我犯过不止一次。5. 排坑3.14.2 常见翻车现场与排查路径这一章我们集中解决 CMake 3.14.2 在 x64 Windows 下最常遇到的几个问题。每一条我都按「现象 → 原因 → 解决」的顺序来写方便你对照排查。5.1 现象一CMakeLists.txt 解析时报未知命令或策略错误现象运行cmake -S . -B build后输出CMake Error at CMakeLists.txt:XX (add_subdirectory): Unknown CMake command add_subdirectory或者CMake 3.14.2 is lower than required. CMake 3.20 required这类信息。原因前一种通常不是add_subdirectory不存在而是因为该命令来自某个模块而你没include()或者命令拼写有误。后一种明确是版本不满足。也有一种情况项目用到了 3.14 之后加入的语法或策略比如cmake_path()是 3.20 的。解决先看cmake_minimum_required是否小于 3.14。如果项目要求高于 3.14你就需要换新版 CMake而不是继续在 3.14 上挣扎。如果项目要求是 3.14 以下却报了未知命令检查命令拼写如果命令来自某个.cmake模块确认include()是否写在前面。举个例子include(CTest)后才有enable_testing()相关功能顺序错了一样会报错。5.2 现象二生成的 exe 是 32 位而我以为 win64-x64 一定是 64 位现象构建完打开任务管理器看进程架构或者用工具查看 PE 头显示 x86。原因CMake 包的位数是 x64但生成目标平台由生成器决定。Visual Studio 生成器如果不加-A x64默认平台可能是 Win32。Ninja/MinGW 环境下默认取决于编译器本身如果你用的是 32 位 MinGW那自然生成 32 位。解决重新配置时显式指定平台。VS 生成器加-A x64Ninja 加-DCMAKE_GENERATOR_PLATFORMx64。然后在 CMakeCache.txt 里确认CMAKE_GENERATOR_PLATFORM的值是空还是 x64。如果缓存里已经写错删除 build 目录重新配置。5.3 现象三使用 Ninja 生成器时提示找不到编译器 cl现象cmake -G Ninja -DCMAKE_BUILD_TYPERelease ..在 Visual Studio 环境下执行报错CMAKE_C_COMPILER not found或者The C compiler cl.exe is not able to compile a simple test program。原因Ninja 只是一个构建调度工具它不提供编译器。你必须在一个能调用cl.exe的环境中运行 CMake也就是先执行了vcvars64.bat或者使用「适用于 VS 的开发人员命令提示符」。很多人直接在普通 PowerShell 里运行 Ninja 生成器自然找不到 MSVC。解决要么改用 Visual Studio 生成器让 CMake 自己找 MSVC要么每次构建前先运行vcvars64.bat再在同一个终端里执行 CMake。这个坑的本质是混淆了「构建工具」和「编译器工具链」的职责。5.4 现象四同时装了多个 CMake 版本命令行调用的不是 3.14.2现象cmake --version输出一个别的高版本或者明明刚配好 PATHwhere cmake显示旧路径。原因系统 PATH 里的顺序比用户 PATH 更靠前或者旧版本的目录还残留在 PATH 中。Windows 命令搜索按 PATH 顺序进行先找到哪个就用哪个。解决在 PowerShell 里执行where.exe cmake看匹配顺序。然后调整 PATH让C:\Tools\cmake-3.14.2-win64-x64\bin出现在更靠前的位置。如果你不希望改动全局 PATH可以直接用完整路径调用比如在 CI 脚本里把cmake变量指向完整路径。这是最可控的方式。注意3.14.2 的 CMake 缓存文件夹名包含了版本号当你切换版本时旧 build 目录的 CMakeCache.txt 记录的是旧版路径直接复用会报错所以切换版本后最好删掉 build 目录重配。5.5 现象五配置成功构建时却报链接器找不到标准库现象cmake --build build在链接一步报错比如LINK : fatal error LNK1104: cannot open file libcmt.lib。原因CMake 配置时代码生成和编译器路径检查通过了但链接阶段找不到 MSVC 的标准运行库。常见于你混合使用了不同版本的 VS 工具集或者在普通命令行里调用cmake --build导致链接器环境变量被清掉了。解决用完整 VS 开发环境执行构建。最稳妥的是从「开始菜单」打开「x64 Native Tools Command Prompt for VS 2019」然后在这个终端里执行cmake --build。如果必须在 CI 里自动化可以在脚本开头调用 VS 自带的vcvars64.bat。注意路径里的具体目录如果用了不同版本请对应修改。6. 我常用的 3.14.2 验证与清理技巧版本锁定之后日常工作中最耗时间的不是写 CMakeLists.txt而是排查「明明改了 CMakeLists 却没生效」「缓存里不知道存了什么」这类问题。下面三个小技巧是我在多个项目里反复用到的。6.1 用 cmake -LAH 快速审查缓存变量cmake -LAH -S . -B build会列出当前构建目录里的所有缓存变量包括CMAKE_GENERATOR、CMAKE_GENERATOR_PLATFORM、CMAKE_BUILD_TYPE、CMAKE_PREFIX_PATH等。它比打开 CMakeCache.txt 更人性化因为会过滤掉内部变量。排查生成器选错、平台类型不对时我第一件事就是跑这个命令。6.2 用 --trace-source 定位 CMakeLists.txt 的解析问题cmake --trace-sourceCMakeLists.txt -S . -B build会逐行打印脚本执行的函数调用。如果你在条件分支里写错if或者foreach很容易通过 trace 看到执行路径。3.14 对 trace 的支持已经很稳定不需要换新版。遇到「为什么这个 message 没打印」类似的问题加上 trace 跑一遍基本能找到答案。6.3 清理缓存删 build 目录比改缓存快得多很多所谓「玄学」问题本质是 CMakeCache.txt 里的路径或生成器残留。换编译器、换版本、换目录位置之后最省心的做法是直接删除 build 目录重新配置。我的习惯是保留一个clean.ps1脚本# 删掉所有构建目录保留源文件 Remove-Item -Recurse -Force build* -ErrorAction SilentlyContinue注意build*会把build-vs、build-ninja等一并删掉。然后重新配置时先确认 PATH 里的 CMake 是 3.14.2再跑cmake -S . -B build -G ...。我之前在一台机器上同时装了 3.14.2 和 3.20结果where cmake指向了 3.20项目用的旧语法直接报错。后来我习惯在每个项目目录下放一个tools文件夹把对应版本的 CMake 解压进去然后用tools\cmake\bin\cmake.exe这种完整路径来构建再也没出现过「版本玄学」。希望这个习惯也能帮到你。本文还有配套的精品资源点击获取