极客工场

Appearance

共 2,196 字预计阅读约 7 分钟

CMake 版本不兼容报错速查 ​

更新时间：2026-10-24。FAQ 速查页，面向在 Linux/macOS 上用 CMake 生成构建系统的同学。CMake 版本不兼容类报错的统一长相是：配置阶段（cmake ..）还没开始编译就停机，报错里要么直接点名「你的 CMake 太老」，要么抛一条 CMP 策略警告甚至把它升级成错误。这类问题的根源不在你的代码，而在「工程声明要什么 CMake」与「机器上实际跑的是哪个 CMake」之间的落差——cmake_minimum_required 写得比本机版本高、PATH 上多版本并存选错了、CMP 新策略行为变了、脚本里用了新版才有的命令、Find 模块在新旧版行为漂移、构建目录里 CMakeCache.txt 还缓存着旧版生成的配置，六根轴顺一遍基本必中。如果是 make 阶段报 No rule to make target，请转 make: No rule to make target 报错速查。

本文要回答的问题 ​

  • CMake 3.20 or higher is required. You are running version 2.8.12 怎么最快解决？
  • 明明装了新版 cmake，为什么 cmake --version 还是旧的？
  • Policy CMP0074 is not set 这类警告为什么有时候会变成错误？
  • 升级 cmake 后原来能配置的工程反而报错了，怎么办？
  • 清构建目录为什么要连 CMakeCache.txt 一起删？

一、报错原文与典型现象 ​

最典型的版本门槛报错（工程路径以 /proj/demo 占位）：

bash
$ cmake -S /proj/demo -B /proj/demo/build
CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.20 or higher is required.  You are running version 3.10.2

CMP 策略类则长这样：

bash
CMake Warning (dev) at CMakeLists.txt:5 (find_package):
  Policy CMP0074 is not set: find_package uses <PackageName>_ROOT variables.
  Run "cmake --help-policy CMP0074" for policy details.  Use the cmake_policy
  command to suppress this warning if the policy is old behavior.

还有一类是新版专有命令在旧版上直接解析失败：

text
CMake Error at CMakeLists.txt:8 (target_link_options):
  Unknown CMake command "target_link_options".

读懂这类报错抓两件东西：工程声明的版本线（cmake_minimum_required(VERSION x.y) 那一行）和你实际跑起来的版本（cmake --version 第一行）。两者一对照，大半问题当场定位。CMP 警告里那串数字编号（如 CMP0074）是 CMake 的行为变更档案号，cmake --help-policy CMP0074 能看完整说明。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
CMake x.y or higher is required本机 cmake 版本低于工程声明cmake --version 对比工程第一行升级 cmake，或评估下调工程声明
装了新版仍报版本不足PATH 上多版本并存，命中旧版which -a cmake 看全部候选调整 PATH 顺序或用绝对路径调用
CMP 警告刷屏或变错误工程没设策略，新版默认行为变更cmake --help-policy CMP编号 看说明cmake_minimum_required 提到对应版本，或显式 cmake_policy(SET CMPxxxx NEW)
Unknown CMake command "xxx"该命令是新版引入，当前版本太老cmake --help-command xxx 无输出升级 cmake，或改用旧版等价写法
升级后 find_package 找不到包Find 模块/策略行为在新版漂移对比新旧版 --trace-expand 输出显式设置 xxx_ROOT 或固定策略版本
换版本后报一堆莫名其妙的错构建目录 CMakeCache.txt 缓存旧配置grep CMAKE_HOME_DIRECTORY build/CMakeCache.txt删整个构建目录重新配置
脚本里 if(VERSION_LESS) 判断失效版本变量比较写法在旧版语义不同cmake --help-command if 查版本条件用 CMAKE_VERSION 显式比较
CI 通过本地报错（或反之）两端 cmake 版本不一致两端各跑 cmake --version统一版本，CI 固定镜像或安装脚本

三、排查决策图 ​

下面这张图是按「版本落差在哪一侧」分岔的标准路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

engineering/make/ts-make-version-mismatch.md D2 示意图

读这张图抓住一个分水岭：cmake --version 与工程声明的版本线一比，落差不大的（左支）是环境问题——装新版或把 PATH 上的旧版挤下去；版本够了还报错的（右支）是工程问题——策略没设、命令太新、缓存残留。两条支路的修法互不通用，先分侧再动手。

四、逐条排查展开 ​

第一步：把两个版本号摆在一起。 九成问题在这一步就有答案：

bash
cmake --version
# cmake version 3.10.2
which -a cmake
# /usr/bin/cmake
# /usr/local/bin/cmake        （另一个版本藏在这里）
head -1 /proj/demo/CMakeLists.txt
# cmake_minimum_required(VERSION 3.20)

which -a 是多版本并存场景的照妖镜：包管理器装的旧版在 /usr/bin，手动装的新版在 /usr/local/bin，谁的 PATH 顺序靠前谁赢。确认办法是对每个候选各跑一次 --version；临时用新版可以直接写绝对路径 /usr/local/bin/cmake -S .. -B ..，长期解法是调整 PATH 或卸掉旧版。

CMP 策略警告的正确处置不是消除警告，而是做出选择。 CMake 每次改变某个行为都会发一个策略编号：旧行为（OLD）保持兼容、新行为（NEW）是新语义。工程把 cmake_minimum_required(VERSION 3.x) 抬到引入该策略的版本以上，所有历史策略自动取 NEW，警告自然消失；不想抬版本线就针对单条策略显式表态：

cmake
cmake_policy(SET CMP0074 NEW)

千万别用 -Wno-dev 把警告压掉就当修好了——那只是把「行为没定」这件事藏起来，换台机器或换个 cmake 版本行为可能突然翻转。

Unknown CMake command 是纯粹的版本断层。 比如 target_link_options 是 3.13 引入的，在 3.12 上就是 Unknown command。处置只有两条路：升级 cmake 到引入该命令的版本；或者在工程要兼容旧版时改用旧写法（链接选项塞进 target_link_libraries 或 set_target_properties(... LINK_FLAGS ...)）。用 cmake --help-command 命令名 能查当前版本是否认识这条命令。

换版本必须清缓存。 CMakeCache.txt 里写死了上次配置用的 cmake 路径、编译器判定结果和一堆内部变量，换版本后在同一个构建目录重跑，新旧信息搅在一起会报出各种不像版本问题的怪错。凡是升级/降级了 cmake，标准动作是：

bash
rm -rf /proj/demo/build
cmake -S /proj/demo -B /proj/demo/build

Find 模块漂移是升级后才暴露的暗坑。 工程没显式设置策略时，升级 cmake 会把一批 CMP 的默认行为从 OLD 翻成 NEW——典型如 CMP0074 让 find_package 开始认 <包名>_ROOT 环境变量，原本能找到的包突然去了另一个前缀。处置不是回退 cmake，而是在工程里显式写出依赖位置（set(curl_ROOT /usr/local)）并把 cmake_minimum_required 抬到引入该策略的版本，让所有策略行为固定下来。

CI 与本地版本对齐。 本地 3.27、CI 镜像里 3.16，工程声明 3.20，就会出现「本地全绿、CI 爆红」或反过来。处置是在 CI 配置里固定 cmake 安装步骤（或用带新版的镜像），并在工程 README 写明最低版本要求，让报错在预期内而不是惊喜。

五、规范做法与预防 ​

  • 版本线写真实最低要求：cmake_minimum_required 不要盲目写最新版，写工程实际用到的最老特性对应的版本，扩大可构建环境面。
  • 策略显式表态：新增策略警告出现时就决定 OLD 还是 NEW，写下来，不要留给默认值。
  • 构建目录一次性：换 cmake 版本、换编译器、换生成器都直接 rm -rf build 重开，不心疼。
  • CI 固定工具链：cmake 版本写进 CI 镜像或安装脚本，开发机与 CI 版本对齐。
  • 多版本共存用显式路径：机器上必须留多个版本时，构建脚本里写绝对路径，不赌 PATH 顺序。

这一篇在知识体系里的位置 ​

本篇是 Makefile 排错速查簇的 CMake 配置篇，定位「cmake .. 阶段就失败、还没轮到编译」：版本与策略问题看本篇；CMake 连编译器都找不到的看 CMake 找不到编译器速查；配置过了、make 展开规则失败的看 make: No rule to make target 报错速查；编译过了链接炸符号的看 undefined reference 链接错误速查。同簇还有权限问题 构建目录 Permission denied 速查 与头文件找不到 fatal error: xxx.h 速查。cmake --version、which -a、--help-policy 三件排查套在所有 CMake 配置类报错间完全通用。

一句话总结 ​

CMake 版本不兼容先把 cmake --version 与工程 cmake_minimum_required 声明摆在一起对比：本机版本低就升级 cmake 或 which -a 找到并存的新版调整 PATH；版本够还报错就查 CMP 策略（--help-policy 看说明后显式 cmake_policy SET NEW 或抬版本线）与新版专有命令；换过版本一律删构建目录清 CMakeCache 重新配置；CI 与开发机版本对齐、工程声明真实最低版本线，这类报错即可基本绝迹。