企业官网建设流程全解析

记得刚入行那几年，我一度觉得 CMake 就是“把编译器、头文件和库路径写在一起”的东西，能出二进制就算成功。直到我接手一个大一点的跨平台 C++ 工程，才开始意识到这套思路的代价：一个项目七八个内部库、十几个可执行目标，所有目录都直接调用全局的 include_directories 和 link_directories，高层 CMakeLists 里堆满了 set() 变量，整个构建系统几乎是靠“约定”和“顺序”在运行。今天我想聊的 C++构建系统（CMake）进阶，不是教你背命令，而是把这套系统当作一个可维护的工程来重新认识。

之所以说是“进阶”，是因为很多基础教程只会教“怎么让某一台机器上能跑起来”；而现实项目里要面对的是：别人怎么接手、换平台怎么办、第三方想用你的库怎么办、Debug/Release 多配置怎么切换、测试怎么进构建流程。这些问题单靠搜片段式的教程很难拼出完整答案。这篇文章适合已经有 CMake 基础、但还没弄清楚 target-based 思路、生成器表达式、安装导出、工具链文件这些进阶主题的开发者。下面按我的实战路径拆开讲，每一部分都尽量说清楚“为什么这么做”，而不只是“怎么配”。

1. 先破除惯性：为什么传统的“目录变量大法”走不远

1.1 很多老教程里的 CMake 写法，问题出在哪

老式 CMake 的典型写法，大概是这样的：

add_subdirectory(src/xxx) add_subdirectory(src/yyy) include_directories(include) link_directories(${THIRD_PARTY_LIB_DIR}) add_executable(main main.cpp) target_link_libraries(main xxx yyy)

在小项目里，这确实能跑。原因在于 CMake 的过程式语法天然有“全局副作用”：include_directories 一旦调用，之后创建的所有目标都会拿到那个头文件搜索路径；link_directories 一旦设置，后面所有链接步骤都会去那个目录找库。听着方便，但它本质是一个“按时间顺序、按全局状态”运行的模型。

问题随之而来。你在顶层先 include_directories(a) 再 include_directories(b)，后续目标的头文件搜索顺序就是 a 优先于 b。一旦两个不同版本的第三方头文件同时存在，编译器可能就会选中“看起来对”的那个，然后程序在运行期出现莫名其妙的崩溃。这类问题最坑的地方在于：它很少在编译期爆出明显错误，更多是“你去查内存越界，查了两天，结果发现是头文件顺序被全局变量污染了”。我帮一个同事排查过类似问题，最后发现他的模块在干净容器里编不过，原因是新容器里的目录加载顺序变了，而之前的构建依赖了 “上一层先 add_subdirectory，然后全局 include 生效” 的隐性顺序。

这类老写法的另一个痛点，是无法表达“这个库到底依赖什么”。一个库如果只是自己在内部用了某个第三方库，它并不需要让所有链接它的目标都知道；但如果它的公共头文件里 include 了第三方库，那么使用方也必须能拿到那个第三方库的路径。这种“依赖可见性”的区分，全局变量写法完全表达不出来。于是项目一复杂，就会出现“所有目录路径都堆在顶层、所有人都在猜到底哪个变量生效”的混乱。

1.2 现代 CMake 的立足点：把信息绑在目标上

现代 CMake 的核心转变，是放弃“全局目录变量”的思维，把所有编译选项、头文件路径、链接库、宏定义和特性要求都绑定到 target（目标）上。目标就是 add_library 或 add_executable 创建出来的那个“对象”，它拥有自己的属性，并能通过 target_include_directories、target_compile_definitions、target_link_libraries 这些命令来设置属性。

举个例子：

add_library(core STATIC src/core.cpp include/core.hpp) target_include_directories(core PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> ) target_link_libraries(core PRIVATE fmt spdlog) add_library(service STATIC src/service.cpp) target_link_libraries(service PRIVATE core) target_link_libraries(app PRIVATE service)

这段代码最重要的不是命令本身，而是可见性关键字 PUBLIC / PRIVATE / INTERFACE 的含义。我用一个直观场景说明：

• 假如 core 是一个日志库，它内部用到了 spdlog，但它的公共头文件里没有 include spdlog，那么 core 对 spdlog 的依赖就是 PRIVATE，意思是“我只是内部实现用了它，外面的人不需要知道”。
• 如果 core 的公共接口里直接 include 了 spdlog，比如它的头文件暴露了一个接受 spdlog 对象参数的函数，那么所有使用 core 的目标也必须能拿到 spdlog 的头文件。这种情况下依赖应该声明为 PUBLIC。
• INTERFACE 则用于那种“只有接口没有实现”的目标。典型就是 header-only 库，或者只提供宏定义和头文件的组件。用 add_library(header_only INTERFACE) 创建后，不需要链接任何 .a/.so，但使用方需要继承它的头文件路径和宏定义。

这种 target-based 写法的价值，相当于在编译器和编译器之间建立了一层“契约”：每个库知道自己需要什么、知道向使用方承诺什么。之后，模块 A 的改动不会因为全局变量而莫名其妙影响到模块 B。我在几个项目里做过类似的迁移，最直观的感受是：不再需要在顶层写一大堆 include_directories，也不用担心目录加载顺序，跨平台编译时的“灵异问题”少了很多。

2. 核心细节解析与实操要点：生成器表达式是“进阶分水岭”

2.1 生成器表达式到底在什么时候被求值

先记住一个关键区别：普通 CMake 变量在 configure 阶段就被求值成字符串，而生成器表达式（Generator Expressions）是延迟到 generate 阶段甚至 build 阶段才被求值的。它能动态地根据当前配置、目标属性、平台和编译器来产生不同的值，因此非常适合表达“与使用场景有关”的信息。

最常见的场景，就是“同一份代码，在构建树里用源码目录路径，在安装后用安装目录路径”。看看常用写法：

add_library(core STATIC ...) target_include_directories(core PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> )

这里$<BUILD_INTERFACE:...>的意思很直白：当 core 还在当前构建树里被其他目标使用时，使用方拿到的是当前源码目录里的 include 路径；$<INSTALL_INTERFACE:...>则是说：当 core 被安装到系统目录、被别人通过 find_package 找到之后，使用方拿到的是安装目录下的相对路径 include。因为安装之后源码目录根本不存在了，如果还拿绝对路径写死，装到哪台机器都会立刻断链。

生成器表达式的另一个典型作用是在编译选项里做“分编译器、分配置”处理：

target_compile_options(common PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/EHsc /W4> $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic> )

很多习惯用 if(MSVC) 判断的人也能达到类似效果，但 if 是在 configure 阶段做分支，只能处理“当前这台机器、当前这一次配置”的情况。一旦遇到 Ninja Multi-Config 这类生成器，同一个构建目录可以生成多个配置，编译器和配置类型都可能动态决定，用 configure 阶段的分支就会力不从心。生成器表达式是唯一稳定可靠的方式。

2.2 常用生成器表达式速查与选型

我对项目里最常用的生成器表达式做了个速查表，方便写到时快速对照：

使用生成器表达式时，我要特别提醒一点：嵌套层级别太深。虽然$<$<CXX_COMPILER_ID:GNU>:-Wall>这种双层写法还能读，但你一旦开始套三四层，比如同时判断编译器、配置、语言，表达式里的逗号和括号稍微错一个，报错信息往往让人非常崩溃。我的经验是：嵌套超过三层时，及时提取成 CMake 变量，或者拆成多个表达式，别为了“一行搞定”牺牲可维护性。

2.3 类接口细节：PUBLIC / PRIVATE / INTERFACE 的“传递规则”

再深入一点看可见性关键字。PUBLIC / PRIVATE / INTERFACE 不是随便选个词，它定义了“使用要求如何传播”。用代码说明：

add_library(core STATIC src/core.cpp) target_include_directories(core PUBLIC include) target_link_libraries(core PRIVATE fmt spdlog) add_library(service STATIC src/service.cpp) target_link_libraries(service PRIVATE core) target_link_libraries(app PRIVATE service)

这条链路的含义：

• service 编译时能拿到 core 的 include 路径，因为 core 对它的 include 是 PUBLIC；但 service 不需要知道 core 的实现用了 fmt 和 spdlog，所以那部分依赖是 PRIVATE，不会继续向外传播。
• app 链接 service 时，不会被强制要求找到 spdlog，因为 spdlog 只是 core 的内部实现依赖。
• 如果哪天 core 把日志实现从 spdlog 换成自研库，service 和 app 的 CMakeLists 几乎不用改。

很多同学在“要不要写 PUBLIC”上犹豫不决，我的建议是：从“头文件里是否真的出现另一个头文件”来判断。编译器在编译一个 C++ 文件时，它看到的是预处理之后的头文件展开，如果 core.hpp 里 include 了 spdlog.hpp，那么使用方必须能找到 spdlog 的头文件。这个判断标准是硬性的，凭感觉写很容易出问题。

3. 可复现的构建入口：CMakePresets 与工具链文件

3.1 用 presets 把“命令行操作”变成工程资产

如果你还在用命令行敲一长串 -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=... -G Ninja 来配置项目，我强烈推荐把配置方式写进 CMakePresets.json。这不是为了省几个字符，而是让每个开发者、每台 CI 机器、每个 IDE 都共享同一套构建入口。

一个最小可用的例子：

{ "version": 3, "cmakeMinimumRequired": { "major": 3, "minor": 20, "patch": 0 }, "configurePresets": [ { "name": "dev", "displayName": "本地开发默认配置", "generator": "Ninja", "binaryDir": "${sourceDir}/build/dev", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", "MY_PROJECT_ENABLE_TESTS": "ON" } }, { "name": "release", "displayName": "发布版配置", "generator": "Ninja", "binaryDir": "${sourceDir}/build/release", "cacheVariables": { "CMAKE_BUILD_TYPE": "Release", "MY_PROJECT_ENABLE_TESTS": "OFF" } } ], "buildPresets": [ { "name": "dev-build", "configurePreset": "dev" }, { "name": "release-build", "configurePreset": "release" } ], "testPresets": [ { "name": "dev-test", "configurePreset": "dev", "output": { "outputOnFailure": true } } ] }

配置好之后，本地只需要：

cmake --preset dev cmake --build --preset dev-build ctest --preset dev-test

CI 上直接用 release preset 就好，所有差异都收敛在这个文件里，不再散落在各家脚本中。这里有个容易踩的坑：任何时候修改了 CMakePresets.json 或 CMakeLists.txt，如果发现配置结果和自己预期不符，先把 build 目录里的 CMakeCache.txt 清掉，再重新配置。因为 preset 里的“隐藏变量”和 cache 变量的优先级在有些场景下会把旧值带进来，让人误以为 preset 没生效。

3.2 工具链文件：交叉编译的入口

交叉编译是进阶绕不过去的坎。其实在 CMake 里，工具链文件要解决的就是三件事：目标平台是什么、编译器在哪、搜索路径怎么限定。一个典型的最小工具链文件如下：

set(CMAKE_SYSTEM_NAME Generic) set(CMAKE_SYSTEM_PROCESSOR arm) set(CMAKE_C_COMPILER /opt/arm-toolchain/bin/arm-none-eabi-gcc) set(CMAKE_CXX_COMPILER /opt/arm-toolchain/bin/arm-none-eabi-g++) set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) set(CMAKE_FIND_ROOT_PATH /opt/arm-toolchain/arm-none-eabi) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

几个关键点：

• CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY 在裸机嵌入式场景里几乎是标配。CMake 默认在 configure 阶段会尝试编译并运行一个小程序来探测编译器，但交叉编译时“运行”这一步往往是失败的；改成只编译静态库，可以避开这个坑。
• CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER 的意思是：查找可执行程序时不要到目标系统的根目录里找，免得找到目标板上的工具；查库和查头文件则只到根目录里找，避免误用宿主机的库。
• 工具链文件负责“在哪里编译、有没有交叉的环境条件”，CMakeLists 负责“编译什么目标、依赖关系如何”。这两层职责不要混在一起。尽量在 CMakeLists 里用语义化变量（比如 CMAKE_SYSTEM_NAME）做条件判断，而不要依赖工具链文件里某个自定义变量的名字，因为不同工具链文件的变量名差异很大。

3.3 缓存变量与选项管理：避免“隐藏变量”的坑

CMake 的缓存变量会跨配置持久化，这是很多人在选项管理上翻车的根源。常见写法：

option(MY_PROJECT_ENABLE_TESTS "是否启用测试" ON)

看似简单，但有个反直觉的行为：假设某台 CI 机器上一次配置时把 MY_PROJECT_ENABLE_TESTS=OFF 写进了 cache，后来 CMakeLists 里把默认值改成 ON，重新 configure 时缓存里的 OFF 仍然会赢，默认值的变化不会自动覆盖缓存。团队里一个成员通过 -D 改过一次选项之后，下次任何人使用 preset 配置时，OFF 还会粘在 cache 里，直到有人手动清 build 目录。

所以我的习惯是：所有可选特性都提供一层“强制覆盖”入口：

if(DEFINED MY_PROJECT_FORCE_TESTS) set(MY_PROJECT_ENABLE_TESTS ${MY_PROJECT_FORCE_TESTS} CACHE BOOL "" FORCE) endif()

这样团队和 CI 在需要时可以直接强制，避免“为什么我改了默认值但没生效”的疑惑。

4. 从构建树到安装树：导出目标与 find_package 的配合

4.1 为什么“能编译”不等于“能被别人用”

很多项目停在“能编译、能运行”这一步，但一旦要交给另一个项目使用，问题就来了。使用方最理想的情况是写个 find_package(MyLib REQUIRED)，然后 target_link_libraries(app PRIVATE MyLib::core)，include、链接参数、传递依赖全部自动配好。要达到这个效果，你不能只 install(TARGETS ...) 把二进制放进目录，还要把目标“导出”出去，让 CMake 能生成一个可被 find_package 读取的配置文件。

核心逻辑是：在构建树里，add_library 创建的目标属性是相对于“当前构建系统”存在的；安装之后，源码路径全部失效，所以要用 install(TARGETS ... EXPORT MyLibTargets) 声明“我要把目标导出到某个命名集合里”，再用 install(EXPORT ...) 生成一个 CMake 配置文件（通常叫 MyLibTargets.cmake），里面记录了这些目标的各种属性。同时给目标加命名空间，比如 MyLib::core，避免多个库导出同名目标时冲突。

一个完整的最小导出示例：

add_library(core STATIC src/core.cpp) target_include_directories(core PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> ) include(GNUInstallDirs) install(TARGETS core EXPORT MyLibTargets ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) install(EXPORT MyLibTargets FILE MyLibTargets.cmake NAMESPACE MyLib:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLib )

实际操作中容易出三个问题：

• 头文件的接口路径忘了拆成 $<BUILD_INTERFACE:...> 和 $<INSTALL_INTERFACE:...>，直接写成绝对路径，安装之后导出目标里还指着源码目录，别人一用就断链。
• 依赖关系没有导出。假如 core 依赖 fmt，你导出 core 时，使用方 find_package 到 core 之后，还需要通过 find_package(fmt) 找到 fmt，并把 fmt::fmt 通过 target_link_libraries(core INTERFACE fmt::fmt) 传出来。否则使用方会遇到一堆找不到符号的链接错误。
• 头文件本身忘了 install。导出目标里的 include 路径只是告诉编译器去哪找，如果实际的 include 目录没有 install，等于路标指向一个空目录。

4.2 Config 模式 vs Module 模式：find_package 到底在找什么

搞清楚 find_package(MyLib) 去哪个文件里找，能省很多排查时间。CMake 有两种模式：

现代 CMake 中，只要库自己提供了 MyLibConfig.cmake 或 MyLibTargets.cmake，通常会自动选择 Config 模式。项目在安装时通过 install(EXPORT ...) 生成 MyLibTargets.cmake，再写一个极简的 MyLibConfig.cmake 把它 include 进来，就完成了 Config 模式的基础。

我建议 MyLibConfig.cmake 保持“极简桥接”的思路：检查必要组件、include MyLibTargets.cmake、必要时用 find_dependency 处理依赖。不要把复杂的平台逻辑写进去。配置文件越简单，出问题的可能性越低。

4.3 实操：让第三方项目“一行接入”

把上面的内容组合起来，一个较成熟的导出设计，衡量标准不应该是安装步骤写得多华丽，而是使用方只需要三行就能接入：

find_package(MyLib REQUIRED) add_executable(consumer main.cpp) target_link_libraries(consumer PRIVATE MyLib::core)

当你能稳定提供这种体验时，说明构建系统已经从“自己项目的编排脚本”进化成了“给别人用的软件包”。这也是我在一些团队里会用来判断构建系统是否成熟的一个硬指标：一个新同事能不能不读内部文档，只凭 find_package 的用法就把依赖链在新机器上搭起来。

5. 进阶分支：测试、多配置与跨编译器控制

5.1 把 CTest 接进构建流程

进阶的另一个标志，是把测试当作构建体系的一部分，而不是构建完成后再手动跑两下。CMake 对测试的集成其实很简单：

include(CTest) if(BUILD_TESTING) add_executable(core_tests tests/core_tests.cpp) target_link_libraries(core_tests PRIVATE core) add_test(NAME test_core COMMAND core_tests) endif()

include(CTest) 会自动提供 BUILD_TESTING 选项，默认 ON。用 if(BUILD_TESTING) 包住测试目标后，使用方可以方便地在配置时用 -DBUILD_TESTING=OFF 关掉测试。

有个细节要格外注意：ctest 执行的时候，工作目录通常被设置到构建目录下的某个测试子目录，而不是你的源码目录。如果你的测试需要读取数据文件，不能在代码里默认“当前目录是源码目录”，建议用编译期宏把数据目录注入测试程序：

target_compile_definitions(core_tests PRIVATE TEST_DATA_DIR="${CMAKE_CURRENT_SOURCE_DIR}/tests/data")

另一个实用技巧：如果用 GoogleTest，可以用 gtest_discover_tests 自动枚举所有测试用例，比手动一个个 add_test 方便得多，测试新增时也不用反复改 CMakeLists。Catch2、doctest 等框架也有类似的 CMake 模块。

5.2 多配置生成器：单配置 vs 多配置的差异

CMake 生成器大致分两类：

• 单配置生成器（Unix Makefiles、Ninja）：配置时通过 -DCMAKE_BUILD_TYPE=Debug 或 Release 决定唯一构建类型，built type 在 configure 时固化。
• 多配置生成器（Visual Studio、Xcode、Ninja Multi-Config）：一个 build 目录可以同时包含 Debug、Release、RelWithDebInfo 等多个配置，配置类型在 build 阶段通过 --config 指定。

这个区别会深刻影响项目里的写法。如果项目里藏着 if(CMAKE_BUILD_TYPE STREQUAL "Release") 这种判断，在多配置生成器下行为往往是不可预测的，因为 CMAKE_BUILD_TYPE 在 multisconfig 下的值可能是空字符串。更稳的做法是用生成器表达式 $<$ CONFIG:Release :...>。

多配置还能顺带解决一个经典问题：Debug 和 Release 运行时库不匹配导致崩溃。使用 MSVC 和 Visual Studio 生成器时，链接器会自动选择当前配置对应的运行时库，只要你不手动去全局覆盖那些变量。如果确实有特殊原因要改，也应该用生成器表达式分配置设置，而不是在全局 CMAKE_CXX_FLAGS 里写死。

5.3 编译选项的“分编译器”管理经验

每个项目总有那么几个“只适合某个编译器”的选项。我自己的做法是把它们集中收进一个函数：

function(apply_project_warnings target) target_compile_options(${target} PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/W4;$<IF:$<CONFIG:Release>,/O2;/O1>> $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall;-Wextra;-Wpedantic> ) endfunction()

看到分号了吗？生成器表达式里分号用来区分列表项。初学者很容易在这里栽跟头：$<$<CXX_COMPILER_ID:GNU,Clang>:-Wall;-Wextra;-Wpedantic>的语义是“如果编译器是 GNU 或 Clang，则分别加入 -Wall、-Wextra、-Wpedantic 三个选项”。但如果想表达“多个选项是同一组”，最好拆成多个独立表达式，或者分多次调用 target_compile_options，可读性和可维护性都会好很多。

6. 常见问题与排查技巧实录

6.1 高频报错速查表

我把自己遇到和帮同事处理过的高频问题整理成了一张速查表：

6.2 实战排查思路

排查 CMake 问题有一个让我屡试不爽的套路：先看 configure 输出，再看生成的构建文件，最后才怀疑编译器。

我帮 A 同学排查过一个具体案例。工程在 Windows 上使用 Visual Studio 生成器可以编过，到 CI 换成 Ninja 后立刻报找不到某个 DLL 的导入库。第一反应是“路径问题”，但把 configure 日志翻出来之后发现，CMake 在找库的时候返回了两个不同的候选路径，一个来自环境变量，一个来自某次 find_library 的 HINTS 路径。两个路径下都有同名库文件，但版本不同，链接后才出现运行期问题。最后我们把 find_library 的搜索顺序固定成“优先项目内第三方目录，其次系统目录”，并用 set(... CACHE FILEPATH FORCE) 把结果锁进缓存，这个问题才算稳定解决。

这个案例的启示是：CMake 报错往往只是表象，真正的坑来自搜索路径的多义性。排查时不要只盯着最后一个报错，要在 configure 阶段把 find_* 族命令实际找到了什么看一遍。理解一个变量“是怎么被找到的”，比知道“它的值是什么”更重要。

6.3 性能优化：大型项目配置和不必要的重编

项目大到一定程度，构建时间会从“能忍”变成“不能忍”。CMake 层面的优化，先把基本功做对，成本通常能降一截。

• 不要让所有目标共享同一个“超级头文件路径”。include_directories(include) 写在顶层，所有子目录目标都会纳入该路径。模块 A 改一个头文件，理论上会把能看到那个路径的所有编译单元都判断为需要重新编译。
• 慎用 add_subdirectory 引入第三方库源码。如果第三方库只需要链接，尽量用 find_package 或 FetchContent 的下载方式；如果必须源码编译，考虑给第三方库单独设置 EXCLUDE_FROM_ALL，并只构建你需要的目标。
• 用 ccache 或 sccache 做编译缓存，CI 上效果尤其明显。CMake 侧只需要设置 CMAKE_CXX_COMPILER_LAUNCHER=ccache 这类变量，业务代码基本不用动。
• 对于 Ninja 单配置生成器，复用 build 目录时增量编译效果不错；但如果你经常改 CMakeLists，Ninja 会自动重新跑 configure。注意，改了 target_include_directories、target_compile_definitions 这类影响编译单元属性的地方，Ninja 会重新执行 configure，但不会把所有编译单元标脏，增量仍然有效。真正伤效率的是“改顶层公共属性导致所有目标依赖关系变化”，那就会变成全量重编。
• 如果一次 configure 实在太慢，可以把项目拆成更合理的 CMake 层次：平台相关代码单独一个模块、纯算法库单独一个模块、UI 层再单独一个模块。拆的意义不只是目录好看，而是让 CMake 能按需 configure 和生成。

6.4 我自己的几个小技巧

最后分享三个很小、但确实帮过我的习惯。

第一，所有 find_package、find_library、find_path 的结果都先打印出来：

message(STATUS "fmt found at: ${fmt_DIR}")

在复杂依赖链里，这一步能省下大量“为什么这个变量是空的”的排查时间。

第二，写函数或宏时，开头先 cmake_parse_arguments，把参数名定清楚。不要仗着 CMake 是过程式语言就零零散散地写，几个月后你自己都有可能看不懂一个多参数封装到底是在用 ARGC 还是 ARGV0。

第三，CMakeLists.txt 里尽量少用 set(... CACHE ...) 直接改全局缓存，除非你确定它需要跨 configure 持久化。否则开发者在两个分支之间切换时，缓存变量很容易变成“幽灵配置”，让所有人以为代码有问题。

做了几年 C++ 项目的构建维护，我最大的体会是：CMake 进阶表面上学的是一堆命令和语法，实际上学的是如何把依赖关系的契约描述清楚。当你把一个项目的构建系统从“一长串顺序执行的全局配置”重构为“一组自描述的目标”之后，最直观的变化是换人接手、跨平台切换、第三方接入都顺了很多。构建系统会从项目的短板，慢慢变成可以稳定依赖的基础设施。如果你正要动手重构某个工程的 CMake 配置，我的建议是别一步到位，先从最小的一两个核心库开始转成 target-based 写法，跑通后再逐步迁移，这样风险最小，效果也最容易验证。