企业官网建设流程全解析

我最早接触 CMake 的时候，说实话挺抗拒的。平时顺手就能编译的小项目，非要弄一个 CMakeLists.txt，还要学一堆命令语法，总觉得是在给简单事情加负担。直到后来开始接手多模块、跨平台的项目，才意识到 CMake 的价值——它解决的根本就不是“编译”问题，而是“构建工程如何组织、依赖如何管理、项目如何在不同环境里复现”的问题。这篇内容就围绕 CMake 构建使用展开，把我从零开始梳理的使用路线、踩过的坑、排查过的报错一次性讲清楚，适合刚入门 CMake 的人通读，也适合已经能跑通简单构建、但还被多目录和依赖问题卡住的朋友查漏补缺。

1. CMake 到底解决了什么问题

1.1 CMake 和 Makefile 的区别

很多人问 CMake 和 Makefile 的区别，最简单的理解是：Makefile 是给 make 这个工具用的构建脚本，它描述的是“哪个文件依赖哪个文件、用什么命令把它们变成目标文件”；而 CMake 本身并不直接编译代码，它生成的是“构建系统文件”，这个构建系统文件可以是 Makefile，也可以是 Visual Studio 的 .sln，还可以是 Ninja 的 build.ninja。

也就是说，CMake 比 Makefile 高了一层抽象。你写 CMakeLists.txt，描述工程结构和构建要求，然后 CMake 根据你当前的操作系统、编译器、生成器，产出一套对应的原生构建配置。这样同一份 CMakeLists.txt，在 Linux 上生成 Makefile，在 Windows 上生成 Visual Studio 工程，不用改逻辑。

举一个直观的例子。一个简单的 Makefile 通常会写死编译器：gcc -o app main.c。换到 MSVC 环境下，这套写法基本失效，你得另写一份。但 CMake 里你只需要写：

add_executable(app main.c)

它会根据当前环境自动选择编译器。这就是“一次编写，多环境复用”的意义。当然实际工程没有这么无脑，还涉及平台判断、编译器特性检测，但是抽象层级的好处就在这——你不需要为每个平台单独维护一套规则。

1.2 CMake 的核心思想：目标是第一公民

CMake 从 3.0 版本开始，设计思路发生了很大变化。早期版本大家习惯写全局变量、全局 include 路径，日子久了经常出现“一个变量改了，整个工程行为变了”的诡异现象。现在的现代 CMake 更强调 target（目标），所有依赖关系都挂在 target 上。

什么叫 target？可执行文件是 target，静态库是 target，动态库也是 target。add_executable和add_library就是在创建 target。创建完之后，你可以给这个 target 设置头文件搜索路径、编译选项、链接库、宏定义。别的 target 依赖它时，这些属性还能通过target_link_libraries传递。

这种设计的好处是：依赖关系不再靠“全局路径”来维系，而是通过 target 之间的显式链接。工程大了以后，这种清晰度能救命。我见过一个旧项目，十几个目录共用一个全局include_directories，后来新同事加了个同名头文件，整个编译链被污染，查了整整一天。如果用现代 CMake 的 target 方式组织，这个问题根本不会出现。

明白了这一点，后面学语法会顺畅很多，因为你知道每个命令在表达什么：不是“往全局塞配置”，而是“给某个目标补充信息”。

2. 从零准备环境：安装、下载与第一个项目

2.1 各平台安装 CMake 的方式

在 Linux 上，CMake 的安装最稳妥的方式是用包管理器，但版本往往偏老。比如 Ubuntu 18.04 自带的 CMake 还停留在 3.10 左右，老版本对现代 CMake 语法支持不完整，很多项目会直接报语法错误。如果遇到这种情况，不要纠结，直接装新版本。

推荐用 pip 安装的方式，简单粗暴：

pip install cmake

装完以后检查版本：

cmake --version

pip 装的 CMake 基本能跟着官方更新走，省去手动编译的麻烦。如果你不想用 pip，也可以去 CMake 官网下载预编译的二进制包，或者用 apt 的kitware-archive源，后者是官方维护的 apt 仓库。

Windows 上最省心的是去官网下载 Windows 版安装包，安装时勾选“Add CMake to the system PATH”。还有个下载镜像的小技巧：官网慢的时候，可以用国内镜像源，具体域名自己搜一下就能找到，速度会快不少。装完之后建议在命令行里先敲一遍cmake --version确认环境变量生效，别等到项目构建时才发现问题。

macOS 用户一般直接用 Homebrew：brew install cmake。

2.2 第一个 CMakeLists.txt

创建一个测试目录，里面放一个main.c：

#include <stdio.h> int main(void) { printf("cmake build demo\n"); return 0; }

然后在同目录创建CMakeLists.txt：

cmake_minimum_required(VERSION 3.16) project(CmakeDemo C) add_executable(cmake_demo main.c)

接着在终端执行：

cmake -S . -B build cmake --build build

-S .指定源码目录，-B build指定构建目录。这两行命令的含义是：先让 CMake 读取源码里的 CMakeLists.txt，在 build 目录里生成构建系统文件；再让 CMake 调用底层工具（make 或 MSVC）完成实际编译。

如果一切正常，build目录下会出现可执行文件（Linux/macOS 下是cmake_demo，Windows 下是cmake_demo.exe）。运行一下就能看到输出。

这里有个新手很容易犯的误区：直接在源码目录执行cmake .然后make。这样做会在源码目录里生成一大堆中间文件，污染源码。用-B指定独立的 build 目录，删除整个 build 目录就可以干净重来，这个习惯必须从第一天养成。

2.3 命令行还是 CMake GUI

Windows 上很多人习惯用 CMake GUI，界面长这样：上面两栏选源码路径和构建路径，中间一大片红色选项框，点 Configure 之后会让选生成器，再用 Generate 生成工程文件。GUI 的优点是直观，适合不熟悉命令行的场景，尤其是配合 Visual Studio 的时候，先生成 .sln，再用 VS 打开。

但我个人还是建议把命令行作为主要操作方式。原因很实际：命令行可以写进脚本、记录到文档里，一键执行；GUI 操作步骤很难复现，别人拿到你的工程还得自己点一遍。而且报错信息在命令行里更完整，排查起来更方便。

如果你是纯 Windows 开发者，完全可以这样配合：用命令行执行cmake -S . -B build生成 VS 工程，然后用 Visual Studio 打开 build 目录里的.sln文件继续开发。这样既保留了 VS 的调试体验，又让构建配置的逻辑收敛在 CMakeLists.txt 里。

3. CMakeLists.txt 核心语法拆解

3.1 工程声明：cmake_minimum_required 与 project

每个 CMakeLists.txt 开头基本固定是这两行：

cmake_minimum_required(VERSION 3.16) project(MyProject C CXX)

cmake_minimum_required指定 CMake 的最低版本，目的是防止老版本 CMake 遇到不认识的命令时报出一些莫名其妙的错误。版本号不要太保守，也别太激进，主流 Linux 发行版的 CMake 版本如果普遍在 3.16 以上，就写 3.16；除非你明确用了更高版本才有的特性，才往上调。

project命令除了声明项目名字，还可以指定项目用到的语言。这里的语言参数会影响 CMake 去检测对应编译器。例如一个纯 C 项目可以写project(MyProject C)，如果混用 C 和 C++ 就写project(MyProject C CXX)。把不用的语言关掉能减少不必要的配置检查，加快 configure 速度。

3.2 add_executable 与 add_library：一切围绕目标

创建可执行文件：

add_executable(app main.c utils.c)

创建库：

add_library(core STATIC core.c) add_library(shared_math SHARED math.c)

STATIC表示静态库，SHARED表示动态库。还有一个常用模式是OBJECT库，它只编译不打包，生成的 .o 文件供其他目标引用，在某些需要把同一批源文件拼到多个目标里的场景很好用，能避免源文件被重复编译。

在写add_executable时，有一个小习惯值得养成：把源文件列表单独用变量定义，而不是全堆在命令里。例如：

set(CORE_SOURCES src/core.c src/parser.c src/utils.c ) add_library(core STATIC ${CORE_SOURCES})

这样后面如果要用条件判断往列表里追加文件，操作会非常方便，不然你只能去改 add_library 那行。

3.3 set、option 与缓存变量

set命令用来定义变量：

set(CMAKE_C_STANDARD 11) set(BUILD_SHARED_LIBS ON)

变量在 CMake 里本质是字符串，列表也是字符串加分隔符。用${VAR}引用变量，用if(DEFINED VAR)来检查变量是否被定义。

option专用于定义开关型变量：

option(ENABLE_TESTS "build unit tests" ON)

这样用户就能在 configure 阶段用命令行覆盖：

cmake -S . -B build -DENABLE_TESTS=OFF

这种设计把工程的“可配置项”暴露出来，比直接改 CMakeLists.txt 优雅得多。

还有一类缓存变量，写起来有点坑。set(FOO bar CACHE STRING "description")，它会写入 CMakeCache.txt，下次 configure 时如果用户没有在命令行重新指定，缓存里的值会继续生效。新手经常遇到的问题就是：改了源码里的set(FOO ...)，重新构建却发现行为没变，原因就是缓存变量还残留着旧值。解决办法是删掉 build 目录重新 configure，或者用cmake -U FOO删掉缓存项。

3.4 if/else 与循环：让构建逻辑活起来

CMake 的if语法接近传统语言：

if(CMAKE_CXX_COMPILER_ID MATCHES "MSVC") message(STATUS "using MSVC") elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU") message(STATUS "using GCC") else() message(STATUS "unknown compiler") endif()

注意 CMake 的if对变量名做了一些“智能”处理，比如if(MSVC)会隐式检查名为 MSVC 的变量是否为真，这在老代码里很常见，但阅读性不好。更明确的写法是if(CMAKE_CXX_COMPILER_ID MATCHES ...)或者if(DEFINED ...)。

循环用得没那么频繁，但foreach和list(APPEND)配合起来很好用：

foreach(src IN LISTS CORE_SOURCES) message(STATUS "source: ${src}") endforeach()

这些语法本身不难，难的是知道“什么时候该用条件判断”。一个典型场景是：Windows 下需要链接 ws2_32 库，Linux 下不需要。这时候条件判断就必不可少了：

if(WIN32) target_link_libraries(app ws2_32) endif()

4. 多目录工程的构建组织

4.1 add_subdirectory 与顶层/子层分工

工程一复杂，所有代码堆在根目录肯定不行。常见的组织方式是顶层CMakeLists.txt负责整体配置，然后通过add_subdirectory引入子目录。每个子目录有自己的CMakeLists.txt，只管自己目录下的内容。

目录结构示意：

project/ ├── CMakeLists.txt ├── src/ │ ├── CMakeLists.txt │ └── main.c └── libs/ ├── CMakeLists.txt └── core.c

顶层 CMakeLists.txt：

cmake_minimum_required(VERSION 3.16) project(MyProject C) set(CMAKE_C_STANDARD 11) add_subdirectory(src) add_subdirectory(libs)

子目录里的 CMakeLists.txt 照常定义自己的 target。这种方式的好处是：每个目录的职责边界清楚，不会出现一个超大 CMakeLists.txt 里堆几千行、找一条配置翻半天的情况。

4.2 依赖关系的显式表达

子目录里创建的 target 在add_subdirectory之后对顶层可见。比如libs/CMakeLists.txt定义了一个库：

add_library(core STATIC core.c)

那么src/CMakeLists.txt里可以这样引用：

add_executable(app main.c) target_link_libraries(app PRIVATE core) target_include_directories(app PRIVATE ${PROJECT_SOURCE_DIR}/libs)

target_link_libraries(app PRIVATE core)这行的作用不只是链接，它还会把 core 的接口属性（比如 public 的头文件路径、编译选项）传递到 app 上。这里的关键字PRIVATE有三种取值，含义如下：

实际项目里最常见的选择是 PRIVATE。比如 app 依赖 core，core 依赖一个第三方库 pthread，那 pthread 链接选项写成 PRIVATE，表示“只有 core 内部需要”，没必要传染给 app。如果你把接口头文件路径写错了作用域，最典型的症状是“编译自己通过，链接别人的目标时报头文件找不到”。

4.3 Debug/Release 与多配置生成器

单配置生成器（Makefile、Ninja）需要通过CMAKE_BUILD_TYPE指定构建类型：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

注意这个变量必须在 configure 阶段设定，不能等到 build 阶段再改。常见的取值是 Debug、Release、RelWithDebInfo、MinSizeRel。

Visual Studio 属于多配置生成器，不需要CMAKE_BUILD_TYPE，而是在cmake --build build --config Release这一步选择配置。这就带来一个差异：如果你在 VS 生成器下写set(CMAKE_BUILD_TYPE Release)，它其实不会生效，因为 VS 工程里所有配置都生成了，最终用哪个配置取决于你 build 时传入的--config。

理解这个差异很重要。我见过有人从 Linux 切到 Windows 后，发现 Debug 和 Release 的宏定义不对，折腾很久，最后才发现是CMAKE_BUILD_TYPE这条经验在 VS 工程里根本不管用。

4.4 编译选项、宏定义与栈大小设置

给目标追加编译选项：

target_compile_options(app PRIVATE -Wall -Wextra)

给目标追加宏定义：

target_compile_definitions(app PRIVATE DEBUG_MODE=1)

Windows 下的 MSVC 编译选项和 GCC 不一样，需要条件判断。如果项目只在 Windows + MSVC 环境下跑，直接写：

target_compile_options(app PRIVATE /W4)

栈大小设置的实质是给链接器传参数。MSVC 下设置栈大小，可以用target_link_options：

target_link_options(app PRIVATE "/STACK:8388608")

这里 8388608 对应 8MB，是十进制字节数。GCC/Clang 下对应的是-Wl,-z,stack-size=8388608或写链接脚本。很多递归算法程序跑着就崩溃，不是代码问题，而是栈空间不够，这种“设置栈大小”的需求在 Visual Studio 工程里通常去属性页里改，但在 CMake 里就归target_link_options管。

5. 第三方依赖管理：find_package 与 FetchContent

5.1 find_package 的基本逻辑

find_package是使用第三方库最正统的方式。以常见库为例：

find_package(OpenSSL REQUIRED) target_link_libraries(app PRIVATE OpenSSL::SSL OpenSSL::Crypto)

REQUIRED表示这个库必须找到，找不到就报错并停止 configure。不带REQUIRED的话找不到也继续走，后面代码里你需要自己判断这个包是否存在。

注意 find_package 找到的并不一定是系统里的库，它背后是一系列查找规则：先看CMAKE_PREFIX_PATH指定的路径，再看系统默认路径。如果你的库装到了非标准位置，需要这样指定：

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/mylib

这是 find_package 最常见的坑之一：明明装了库，却报告找不到。原因就是前缀路径没配。

5.2 报错：The following variables are used in this project

这实际上是 CMake 在发现某些变量被使用但值为空或 NOTFOUND 时打印的提示。完整的报错信息长这样：

CMake Error: The following variables are used in this project, but they are set to NOTFOUND.

这条报错背后往往是某个 find_package 或 find_path 没有真正找到目标路径。例如 header-only 的库，通常会用一个变量记录头文件路径，如果没找到，变量值为XXX_INCLUDE_DIR-NOTFOUND，CMake 就会报这个错。

排查思路分三步：

1. 看完整报错里到底是哪个变量 NOTFOUND，记下来。
2. 回到 CMakeLists.txt 里搜这个变量是在哪里赋值的。如果是find_path或find_package得到的，说明查找路径没覆盖到实际安装位置。
3. 手动用-DCMAKE_PREFIX_PATH指一下路径，或者检查环境变量，再重新 configure。

这个报错还有一个常见来源：你在 CMakeLists.txt 里用${FOO}引用了某个从未被定义的变量，虽然 CMake 不会直接说变量不存在，但某些工具会把它视为 NOTFOUND。所以检查时也顺便确认变量名有没有拼错。

5.3 FetchContent：直接拉源码构建依赖

有些库没有提供 CMake 配置文件，或者版本老到没有 find_package 支持，这时候可以考虑FetchContent：

include(FetchContent) FetchContent_Declare( nlohmann_json GIT_REPOSITORY https://github.com/nlohmann/json.git GIT_TAG v3.11.2 ) FetchContent_MakeAvailable(nlohmann_json) target_link_libraries(app PRIVATE nlohmann_json::nlohmann_json)

FetchContent 会在 configure 阶段把源码 clone 到本地，并直接作为子项目加入构建。这个机制非常适合现代 C++ 项目的依赖管理，但代价是首次构建耗时明显增加，而且需要网络能访问到对应仓库。

实际使用中有两个问题要提前防：

1. 版本别用main或master分支，必须固定 tag 或 commit hash，否则不同时间拉到的代码不一样，构建可复现性直接没了。
2. 国内网络访问 GitHub 时，clone 可能会超时。解决办法是配置FETCHCONTENT_CMAKES_CMAKE_GIT_REPOSITORY或换成镜像仓库地址，这个根据实际情况调整。

依赖三方的选择原则我讲一句：能用find_package优先find_package，它走的是系统已安装的库，性能和稳定性都更有保障；项目里离散的小依赖，才考虑用 FetchContent 锁版本。

6. 高频报错与构建排查实录

6.1 文件为什么还在被编译：不参与构建的几种可能

有朋友问“某个源文件已经从 add_executable 里移除了，构建时还提示它在编译”，这种诡异情况我遇到过几次，根因基本都是这三个之一：

• 找到了旧构建目录。你改了 CMakeLists.txt，但 build 目录里的构建系统文件没有重新生成。cmake --build不会自动感知 CMakeLists.txt 里改动这种情况，它只会根据 make 依赖关系去部分重跑。改动较深时，最稳妥的办法是删掉 build 目录重新 configure。
• 文件被别的目标引用了。你只把它从一个 target 的源文件列表里移除，但另一个 target 还在编译它，这是最常见的情况。
• 有第三方目录通过 FetchContent 或 add_subdirectory 引入了同一份源文件，你在项目里看到的是自己目录里的副本，构建的其实是依赖目录里的副本。

排查方法：在构建输出里找编译命令，看它到底在编译哪个路径的文件，跟着路径追。

6.2 构建缓存残留导致的问题

CMakeCache.txt 是 configure 阶段生成的缓存文件，里面记录了之前所有的变量值。很多人遇到“改了选项没生效”“改了路径没生效”的问题，先别怀疑语法，先确认是不是缓存作祟。

最彻底的办法是删掉 build 目录重新构建。如果你不想全删，也可以指定重新 configure 时覆盖某个变量：

cmake -S . -B build -DFOO=bar

但如果变量类型是缓存变量或内部变量，你得记得用-U FOO先把旧缓存删掉。

这个坑在 CI 环境里不明显，因为 CI 一般每次都是全新目录；反而是本地开发时，一个 build 目录用很久，问题就来了。我现在个人的习惯是：遇到和配置相关的问题，二话不说先删 build 目录。虽然重新 configure 花一点时间，但至少能排除一个最大的干扰项。

6.3 找不到头文件、找不到库的常规解法

“fatal error: xxx.h: No such file or directory”基本都能归到路径问题上。顺序排查：

1. 库安装了吗？系统里有没有对应文件。
2. find_package找到变量了吗？可以写一行message(STATUS "xxx path: ${XXX_INCLUDE_DIR}")打印出来确认。
3. target_include_directories 有没有加对路径？故意多检查几遍路径拼接，${PROJECT_SOURCE_DIR}拼错一个目录层是常见错误。
4. 如果是编译过但后来找不到，可能是库里用了相对路径，换个构建目录就废了。

6.4 路径带空格与中文目录的坑

Windows 下工程路径带空格的场景非常多。大部分情况下 CMake 能处理，但到了某些第三方库或生成规则那里就会出问题。尽量避免把项目放进C:\Users\张三\My Project\这种路径，如果绕不开，记得在字符串里用引号保护：

target_include_directories(app PRIVATE "${PROJECT_SOURCE_DIR}/include")

CMakeLists.txt 里尽可能给路径加引号，不要裸写。这个毛病养成习惯后，能省掉很多莫名其妙的“构建失败”。

7. 工程化落地：从玩具项目到真实项目

7.1 用 CMakePresets.json 统一构建配置

一个工程如果只是自己本地跑，命令行参数随便敲没问题。可一旦要分享给同事，或者要上 CI，各种-D参数就会变成巨大的心智负担。CMake 3.19 开始正式支持CMakePresets.json，可以在项目根目录固化配置。

简单的示例：

{ "version": 3, "configurePresets": [ { "name": "dev", "displayName": "Dev Build", "generator": "Ninja", "binaryDir": "${sourceDir}/build/dev", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", "CMAKE_EXPORT_COMPILE_COMMANDS": "ON" } } ], "buildPresets": [ { "name": "dev", "configurePreset": "dev" } ] }

保存之后，直接：

cmake --preset dev cmake --build --preset dev

别人拿到工程，不需要理解复杂的参数，一条命令就复现了构建环境。这个文件强烈建议提交到版本库。

7.2 导出 compile_commands.json 方便编辑器与排查

给 configure 命令加一个变量：

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

构建目录里会生成compile_commands.json，它记录每个源文件的精确编译命令。这东西有两大用途：

1. 让 clangd、VS Code 的 C/C++ 插件直接读取，得到准确的语法提示和跳转，不用手动配置 include 路径。
2. 排查诡异编译问题时，可以精确看到编译命令里实际包含了哪些宏、哪些头文件路径，比瞎猜强太多。

Principal一个习惯：几乎所有项目我都会开启它，属于低投入高回报的配置。

7.3 Visual Studio 配合 CMake 的日常开发流

在 Windows 上用 Visual Studio 做 CMake 项目，有几种打开方式可以选择。

一种是先cmake -S . -B build生成.sln，然后打开它。这种方式适合历史项目，IC 体验和普通 VS 项目完全一致。

另一种方式是 Visual Studio 自带的“打开文件夹”功能直接打开源码目录，VS 会自己扫描 CMakeLists.txt 并配置。这种方式不用手写-B参数，VS 会管理一套缓存目录，用起来最省心。缺点是它生成的构建目录不在你的工程目录内，找日志文件时需要去 VS 的配置里看实际构建路径。

两种方式我都用过。如果你要兼顾命令行脚本，更推荐第一种：生成 .sln 后，既能继续用 VS 开发，也能在命令行里cmake --build build --config Release完成打包构建，二者互不干扰。

7.4 交叉编译与嵌入式场景的构建思路

碰到 RK3566 之类的嵌入式板子，构建系统本身没折腾明白，最后发现缺 WiFi 驱动之类的硬件支持，这种情况我见得太多了。交叉编译的核心不是 CMake 有什么特殊命令，而是告诉它“我不要用本机的编译器，我要用目标平台的编译器”。

最标准的做法是设置编译器相关变量：

cmake -S . -B build \ -DCMAKE_SYSTEM_NAME=Linux \ -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \ -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \ -DCMAKE_SYSROOT=/path/to/sysroot

CMAKE_SYSROOT指定目标平台的头文件和库所在目录，避免 CMake 探测到主机系统的库，导致链接出一堆 x86 的目标文件。交叉编译里遇到的所谓“没有 WiFi 驱动”，往往只是根文件系统里缺驱动模块，跟 CMake 本身没什么关系。你只需要保证跨编译的产物正确，驱动模块是作为内核模块或系统包单独处理的，不要混在一起排查。

交叉编译建议用 toolchain 文件，而不是每次敲一堆-D：

# toolchain-arm64.cmake set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++) set(CMAKE_SYSROOT /path/to/sysroot)

配置时一行搞定：

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=toolchain-arm64.cmake

这样做的优势很明显：toolchain 文件可以放进版本库，团队里谁都能复用；同时避免把一堆敏感参数写进命令行历史。

8. 一些真实踩坑后的经验总结

第一次自己手写 CMakeLists.txt 是在一个只有三个源文件的小工具上，当时觉得“搞这么复杂干嘛”。后来这个工具慢慢长到 40 多个目录、上百个 target，我回头看那个最初的简单配置，发现用 CMake 的最大好处不是第一次构建多顺利，而是每一次改动都有迹可循：依赖关系在 target 上清楚挂着，构建选项固化在预设文件里，删掉 build 目录就能得到和 CI 完全一致的构建环境。

这里分享几个从实际操作里沉淀下来的习惯，不算什么高深技巧，但能直接降低日常使用成本。

第一，所有路径都写带引号的形式，不要裸写。第二，源文件列表尽量收敛在目录各自的 CMakeLists.txt 里，不要让顶层的 list 越来越长。第三，日常开发用 Debug 构建，出包用 Release 构建，两个构建目录分开，这样出了问题能最快定位是逻辑问题还是优化引入的问题。第四，遇到任何和“配置没生效”“编译用的还是旧文件”相关的怪问题，先把 build 目录删了再说，这类问题里有一半只是缓存在作怪。

关于 CMake 的版本升级，建议保持关注大版本更新，但也不用跟得太快。真正影响日常使用的是那些现代 CMake 的 target 模型和 preset 能力，早点学会直接用，比看一遍语法说明有用得多。说白了，CMake 不是一门需要背的语言，它是一个帮你想清楚工程依赖关系、再把这种关系稳定复现出来的工具。用熟之后，你会发现项目结构是什么样的，构建系统几乎就是照着那个结构映射过去的，到时候 CMakeLists.txt 写起来就跟记笔记一样自然。