C++项目结构设计实战：从零构建可扩展的CMakeLists.txt工程-代码聚汇网

C++项目结构设计实战：从零构建可扩展的CMakeLists.txt工程

没伞请奔跑i·2026-09-04·阅读 83 GEO检测（免费）

C++项目结构CMakeLists.txtCMake教程

|难度：普通|阅读约 44 分钟

搞C++的人大概都经历过这种尴尬：代码能跑，但项目一复杂就乱成一锅粥，头文件不知道往哪儿放，第三方库链接全靠“运气”，换一台电脑、换一套编译器就编译不过。每次遇到这种问题，我很清楚，根子多半不在代码逻辑上，而在项目结构和CMakeLists.txt从一开始就没搭好。我在一线用C++写了十几年，接手过乱七八糟的老工程，也从零搭过不少跨平台项目，今天就把“怎么组织一个C++项目”“怎么写一份能撑住规模的CMakeLists.txt”这两件事一起讲透。

这篇内容不是学院派教条，是我在实际工作里踩坑踩出来的经验总结。它适合刚入门、想搞懂C++工程该怎么组织的同学，也适合一直用Visual Studio或者Dev C++“一键编译”、想转成跨平台CMake构建的人。只要你能看懂最基础的C++语法，剩下的事我尽量替你趟平。

1. 项目结构不是小事，它决定了项目能走多远

1.1 一个烂项目是怎么一步步腐烂的

我见过太多“能跑就行”的项目，最后烂得没法收拾。它们通常长这样：所有.cpp文件和main.cpp堆在同一个目录里，头文件也直接扔在根目录，甚至还有src1、src2、src_old、src_final_xxx这种幽灵目录。CMakeLists.txt更是从头到尾只有一份几十行的“大锅炖”，所有源文件靠file(GLOB ...)一把抓进来，编译器选项、链接库全写在一起。

这种结构在项目只有两三千行代码时没有太大问题，但随着功能增加，问题会集中爆发：

头文件和实现文件混在一起，想找一个功能的代码，得在十几个文件里来回翻。
一个编译单元改动，CMake那边触发的重编范围莫名其妙扩大，增量编译越来越慢。
任何人加入项目，都要先花半天“考古”才能搞清楚哪些文件是正在使用的，哪些是废弃的。
一旦要接第三方库、要把某个模块拆成独立库发布，你会发现没有清晰的模块边界，完全无从下手。

我在一个老项目里还见过更夸张的：同一个文件被复制了三份放在不同目录，改了其中一份，另外两份没改，程序在特定条件下跑出诡异结果，查了两天多才发现是三份拷贝不一致导致的。这个教训让我彻底明白，项目结构不是“排版好不好看”的问题，它直接影响代码的可维护性和团队的协作效率。

1.2 适合多数项目的目录骨架

我平时从零起项目，尤其是想做成一个会长期维护、甚至打算给别人复用的工程时，一般用下面这套骨架：

text复制my_project/
├── CMakeLists.txt
├── cmake/                 # 自定义的CMake模块与工具脚本
├── include/
│   └── my_project/        # 对外暴露的头文件，目录嵌套避免冲突
├── src/                   # 实现文件
│   ├── CMakeLists.txt
│   ├── module_a/
│   └── module_b/
├── tests/                 # 单元测试/集成测试
│   └── CMakeLists.txt
├── examples/              # 给使用者的示例代码
│   └── CMakeLists.txt
├── third_party/           # 第三方依赖，尽量放这里统一管理
├── scripts/               # 辅助脚本，比如打包、代码格式化
└── README.md

这套骨架的核心思想是“按功能模块分目录”，而不是“按文件类型分目录”。什么叫按功能模块分？比如你要写一个图像处理库，里面既有读取、缩放模块，又有滤镜模块，那就拆成src/io/、src/filter/这样的小目录，而不是把所有.h放一个include/，所有.cpp放一个src/就完事。模块边界的意义是：当你需要增加一个“水印”功能时，你很清楚地知道该在哪个目录新建文件、头文件暴露到什么位置。

include/my_project/这一层嵌套，很多人不理解：为什么头文件目录还要再套一层同名目录？我吃过亏后彻底认同这个做法。假设你的项目叫image_tool，如果头文件是#include <image_tool/loader.h>，这个路径天然带上了命名空间一样的隔离效果，就算多个组件都有一份loader.h，也不会因为当头文件被平铺到某个全局include目录时互相覆盖。这是C++工程里很典型的约定俗成，越早接受越省事。

1.3 结构设计里的几条铁律

这些铁律不是标准规定的，是我在实际协作里总结出来、每次用都觉得“真香”的规则：

每个目录的职责要单一：src只放实现，tests只放测试，examples只放示例。永远不要在src里混进一堆测试用的小程序。
头文件尽量自包含：任何一个头文件，单独include它都应该能编译通过。我检测的办法是让每个.cpp第一行就include它对应的头文件，这样编译期就能暴露头文件依赖缺失。
任何外部依赖都要有明确交代：用CMake管理的项目，依赖要么通过find_package查找，要么明确放到third_party并写清楚版本。最怕的就是“这个库我放在C盘某个目录了”这种口头约定。
测试和示例不要和业务源码深度耦合：测试代码可以依赖src内部逻辑，但不要把测试逻辑写进生产代码里。

有了这个目录底子，接下来才轮到CMakeLists.txt表现。结构是项目的骨架，CMakeLists则是把骨架和构建系统连接起来的筋络。很多新手一上来就盯着CMake语法看，结果项目还是一团乱麻，原因就是顺序反了：结构没定清楚，CMake怎么写都别扭。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. CMakeLists.txt到底在帮我们做什么

2.1 一句话理解CMake的定位

CMake不是传统意义上的“编译器”，也不是简单“替代Makefile的脚本工具”。它更像是一个“构建系统生成器”：你给它一份描述项目结构、编译需求、依赖关系的CMakeLists.txt，它帮你生成对应平台下的构建工程，在Linux上可能是Makefile，在Windows上可能是Visual Studio的.sln工程，在macOS上可能是Xcode工程。

这个定位很重要，因为你一旦明白“CMake是生成器”，就不会纠结“为什么我的CMakeLists.txt在Windows和Linux上长得不一样”了。你要做的是写一份尽量跨平台的描述，剩下的交给CMake去适配。这也解释了为什么现代C++项目几乎都把CMake当默认选择：不管团队里有人用Visual Studio、有人用CLion，还是CI服务器是Linux环境，只要仓库里有一份像样的CMakeLists.txt，大家就能用同一套逻辑构建出不同平台的原生工程。

2.2 最小可用版：四行代码建项目

一个最简单的可执行程序，CMakeLists.txt长这样：

cmake复制cmake_minimum_required(VERSION 3.16)

project(my_app VERSION 1.0.0 LANGUAGES CXX)

add_executable(my_app main.cpp)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

把这段内容放在和main.cpp相同目录下，然后在该目录执行：

bash复制cmake -S . -B build
cmake --build build

build目录下就会生成可执行文件my_app（Windows下是my_app.exe）。如果你用Visual Studio的生成器，会把整个.sln工程生成好，直接用VS打开就能继续开发调试。很多新手在这里把命令记混，其实核心只有两条：cmake -S告诉它在源码根目录找CMakeLists.txt，-B告诉它构建文件生成到哪里。源码目录和构建目录分开，这本身就是一个好习惯，后面单独讲。

2.3 常用字段拆解：每条配置背后都有为什么

cmake_minimum_required(VERSION 3.16)这行，表面上是告诉用户“你的CMake至少得3.16”，实际上有很多隐含作用。CMake的语法和函数行为在不同版本间有变化，如果项目用到了某个高版本才有的特性，比如target_compile_features之类，你写了这行，CMake就能在很老的环境上提前报错而不是编译到一半才出诡异问题。我一般不会把版本标得太低，除非明确要做老平台兼容，3.16以上是目前比较稳妥的底线。

project()不只是起个名字。它会帮你设置一系列变量，比如PROJECT_NAME、PROJECT_SOURCE_DIR、PROJECT_BINARY_DIR。后续要用到源码路径、构建路径时，优先用这些变量，而不是自己写死一个/home/xxx或者C:/Users/xxx。我还习惯在project()里直接把版本号和语言声明出来，LANGUAGES CXX可以避免不必要的C编译器检测，省那点时间倒无所谓，主要是语义更清晰。

add_executable和后面会说的add_library是真正定义“目标”（target）的命令。现代CMake的哲学就是一切围绕target展开。一个target有自己的源文件、头文件搜索路径、编译选项、链接库，然后通过target_link_libraries把这些target之间的关系也表达清楚。我见过老式CMake里一堆include_directories()和link_directories()，在项目只有一两个target时问题不大，一旦target多了，这些全局设置会让所有target都背上根本不需要的头文件路径和链接库，很容易引发头文件冲突、符号重复定义。所以我强烈推荐从学的时候就直接养成target化思维。

set(CMAKE_CXX_STANDARD 17)的作用相当于给编译器加上-std=c++17参数。需要特别注意的是，CMAKE_CXX_STANDARD只是一个“最低标准”，它默认还不强制，所以我还习惯加一行set(CMAKE_CXX_STANDARD_REQUIRED ON)，告诉CMake：如果编译器不支持C++17，直接报错，别自己偷偷降级成C++14硬编。这两个变量在3.1之前不是原生支持，这也是我建议CMake版本别太老的原因之一。

3. 手把手搭一个规范化C++项目

3.1 先定需求，再谈搭建

只看个例没意思，我拿一个场景来走一遍完整流程。假设我们要做一个给图像数据加“高斯模糊”的小工具，里面有一个可复用的算法模块和一个命令行入口。这个例子很典型：有核心库、有可执行程序、有对外头文件、还要链接第三方库（我们用OpenCV来读写图片）。项目名就叫blur_tool。

正常的拆解思路是：算法和入口是两种不同性质的代码，算法模块未来可能被复用，入口只服务于当前这个工具。所以算法应该做成一个库（library），入口做成可执行程序，程序通过链接库的方式使用算法模块。这样就完成了“模块边界”的分离，未来就算要换一套命令行解析库，算法核心也不用动。

3.2 一步一步写CMakeLists

text复制blur_tool/
├── CMakeLists.txt
├── src/
│   ├── CMakeLists.txt
│   ├── main.cpp
│   └── gaussian/
│       ├── gaussian_blur.h
│       ├── gaussian_blur.cpp
│       └── CMakeLists.txt
├── tests/
└── third_party/

如果整个项目只用一份CMakeLists.txt把所有源文件列出来，目录结构就算重新设计也发挥不了太大作用。CMake工程讲究“层层包含”，根CMakeLists负责把子目录的CMakeLists汇总进来，每个子目录只关心自己的内容。所以这里我建了三层：

根目录的CMakeLists.txt：

cmake复制cmake_minimum_required(VERSION 3.16)

project(blur_tool VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_subdirectory(src)

enable_testing()
add_subdirectory(tests)

src/gaussian/CMakeLists.txt，也就是算法模块库：

cmake复制add_library(gaussian_blur
    gaussian_blur.cpp
)

target_include_directories(gaussian_blur
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}
)

target_link_libraries(gaussian_blur
    PRIVATE
        ${OpenCV_LIBS}
)

注意这里gaussian_blur.h和gaussian_blur.cpp处在同一目录，target_include_directories写的是当前目录而不是某个脱离实际的绝对路径。PUBLIC的含义是：这个库的使用者也能看到这条头文件路径；如果只是实现里用了某个头文件、对外接口不暴露，那就用PRIVATE。这个可见性语义一开始容易混，但搞清楚后能避免很多“库编译好了，链接时头文件却找不到”的尴尬。

src/CMakeLists.txt：

cmake复制add_executable(blur_tool main.cpp)

target_link_libraries(blur_tool
    PRIVATE
        gaussian_blur
)

再看main.cpp里如果写#include "gaussian/gaussian_blur.h"能否找到？关键在于include路径是怎么组合的。我们把src/gaussian目录以PUBLIC形式暴露给了gaussian_blur库，而blur_tool私有链接了gaussian_blur。当编译器编译main.cpp时，它会拿到从gaussian_blur传递过来的include路径，也就是src/gaussian目录。在main.cpp里写的#include "gaussian/gaussian_blur.h"，其实隐含了一个前提：include搜索路径得能拼出gaussian/gaussian_blur.h这个相对路径。但这里暴露的是src/gaussian本身，搜索路径下直接找的是gaussian_blur.h，所以实际应该写#include "gaussian_blur.h"才对。

这个问题非常典型，好多人就在这里开始困惑。解决的办法有两种：一是把src/gaussian的路径改成暴露src目录，这样#include "gaussian/gaussian_blur.h"就成立，代价是暴露范围更大；二是干脆把对外头文件放在项目统一的include/blur_tool/下，add_library里既加源文件也加头文件，目标更清晰。我个人的习惯是：如果一个模块只在项目内部使用，没有对外发布计划，就用简单方案；一旦以后可能被别的项目或团队复用，就尽早把公开头文件移到外面，从第一天就养成“接口与实现分离”的意识。

3.3 引入第三方库的正确姿势

继续上面的例子，如果算法库里要调用OpenCV的函数，还需要在根CMakeLists里找包：

cmake复制find_package(OpenCV REQUIRED)

这条命令执行时，CMake会在默认路径和CMAKE_PREFIX_PATH指定的路径里寻找OpenCV的配置文件，找到之后会生成一个叫OpenCV_LIBS的变量以及类似OpenCV_INCLUDE_DIRS之类的变量。早期CMake风格是把这两个变量手动塞到include_directories和target_link_libraries里；现在的做法更优雅，OpenCV本身就导出了opencv_core这种target，所以可以这样：

cmake复制find_package(OpenCV REQUIRED COMPONENTS core imgproc imgcodecs)

target_link_libraries(gaussian_blur
    PRIVATE
        opencv_core
        opencv_imgproc
        opencv_imgcodecs
)

用target方式链接，头文件目录和依赖关系都由库自己带过来，少了好多手工拼变量的环节。能做到这一步，是因为OpenCV较新版本已经用CMake把自身target导出给了下游；版本比较老的话，还是得老老实实用OpenCV_INCLUDE_DIRS。这给我一个体会：引入第三方库时，第一时间去查它官方提供的CMake使用示例，比自己凭空猜变量名要快得多。

有个容易踩的坑是：find_package(OpenCV REQUIRED)必须放在使用它的那个CMakeLists.txt之前。如果你的项目根目录find了OpenCV，子目录就能直接用；如果只在某个子目录里find了，那只有它自己以及它后续的add_subdirectory部分能用，别指望平行目录也能拿到这个结果。

3.4 编译选项和构建目录的细节

再补充一个很容易被忽略的细节：生成目录和源码目录分开。我见过有人图省事，直接在源码根目录执行cmake ..，于是在源码目录里生成了成堆的CMakeCache.txt、CMakeFiles目录。这些东西一旦混进源码目录，轻则让IDE索引变慢，重则影响版本控制，每个人都提交一份Cache文件到Git里，团队协作直接乱套。

所以我开头列的两条命令里才会特意写-B build。这个习惯从第一次执行cmake就要养成。后续如果你想知道当前整个项目到底配置了哪些变量，可以用cmake -LAH build查看，这在排查问题时非常有用。

编译器选项方面，我通常不放一堆-O2 -Wall到某个全局变量里，而是针对每个target单独开。比如对内部代码，我会把警告开得很满；对第三方头文件引入的源码，反而要谨慎，因为第三方库的头文件里可能有各种不合口味的写法，开满警告会把真正有用的问题淹没掉。

cmake复制target_compile_options(blur_tool PRIVATE -Wall -Wextra -Wpedantic)

这条配置里PRIVATE表示这些警告选项只对blur_tool自己生效，不会污染链接到的gaussian_blur库。要是你忘了写PRIVATE，默认是PUBLIC，那么这个选项就会传给所有链接了它的目标，容易导致“编译我自己的目标时带上了别人的编译选项”这种玄学问题。

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

4.1 “找不到头文件”到底是谁的问题

错误信息类似：

text复制fatal error: gaussian_blur.h: No such file or directory

遇到这类报错，我先不急着加路径，而是按顺序排查：

头文件本身在这个项目里存不存在？是不是拼写错误、路径大小写不一致？Linux路径大小写敏感，Windows不敏感，Windows上能编过的代码换到Linux全挂，这个我遇到过不止一次。
目标之间有没有建立链接关系？假如blur_tool忘了target_link_libraries链接gaussian_blur，那么即便gaussian_blur自己配置了PUBLIC头文件目录，blur_tool也拿不到那个include路径。
target_include_directories的可见性是PRIVATE还是PUBLIC？如果是PRIVATE，使用者目标一样拿不到目录。
是不是用了绝对路径？比如把某个开发机上的C:/work/opencv/include写进了CMakeLists，这台机器能编，换个环境必炸。绝对路径是CMakeLists里最需要消灭的东西。

排查顺序的价值在于，它能帮你区分“路径配置缺失”和“依赖关系错误”。很多时候问题不是缺一条路径，而是target结构没表达对。

4.2 链接阶段的undefined reference怎么查

编译通过、链接报错的排查思路完全不同。比如：

text复制undefined reference to `cv::GaussianBlur(...)`

这种问题多半是链接库缺失，或者库的链接顺序不对。CMake的target模型里，链接顺序通常已经被自动处理好了，只要你通过target_link_libraries声明了关系。但如果是手动把库名塞进target_link_libraries(gaussian_blur PRIVATE opencv_imgproc opencv_core)这种写法，顺序在某些旧式链接器上会有影响，原则是“被依赖的库放后面”。

还有一种情况是库本身编出来了，但链接的Release/Debug配置和运行库对不上。这在Windows上尤其常见：你编译用的是Debug版，手动链接了Release版的.lib，程序运行时就会崩出各种莫名其妙的内存错误。用CMake的target语义通常会根据配置自动选择对应版本，但如果是手写路径链接第三方预编译库，就一定要确认版本匹配。

4.3 CMake过程报错的常见雷区

有这么几条命令的报错我见过特别多：

cmake_minimum_required版本太低，比如3.10，但后面用了CMake 3.16才支持的写法，会直接提示需要更高版本。处理办法不是把版本号改成3.30“骗过”检查，而是去查当时用的特性的最低版本要求。我之前遇到过项目为了用target_sources里的某个新特性，就把CMake最低版本抬到3.18，结果CI上用的老Linux发行版带的CMake还是3.13，全部编不了。这是一个典型的版本管理问题。

报错：CMake Error at CMakeLists.txt:3 (project): ...。行号正好指向project()的情况非常多。如果后面跟着generator: Visual Studio ...相关字眼，通常是Windows下安装的VS版本和CMake探测结果不匹配，或者多个VS版本并存。我在新机上配环境时常用：

bash复制cmake -S . -B build -G "Visual Studio 17 2022" -A x64

显式指定生成器和平台架构，能少很多没头没脑的探测。

add_subdirectory目录不存在或重复添加，也会直接报错。有时候报的目录路径和你预期的完全不一样，那要先检查是不是CMakeCache没有清干净。这种老缓存问题很隐蔽，我处理办法是定期把整个build目录删掉重新配置。

4.4 和vscode配套使用时的额外注意点

现在很多人在vscode里写C++，几个热词里也反复出现“vscode配置c/c++环境”。在vscode里配合CMake，有几个配置我建议一步到位：

安装官方C/C++扩展和CMake Tools扩展。
让CMake Tools从CMakeLists.txt读取配置，而不是手动在c_cpp_properties.json里手写一堆include路径。因为前者会根据target关系自动把include路径递给IntelliSense，保持一致；后者很容易和CMake里的真实配置脱节，比如你在CMake里加了新依赖，却忘了同步到vscode，编辑器就一路飘红。
如果要用调试功能，先让CMake Tools配置好构建目录，vscode的cmake调试配置会自动识别target，不需要自己手写复杂的launch.json。

实际项目里我还遇到过一个常见问题：同一个工作区可能有多个CMakeLists.txt，CMake Tools有时分不清该用哪一个。这时可以在.vscode/settings.json里用cmake.sourceDirectory指定源码根目录，直接锁死目标。

注意：vscode里如果编辑器显示“找不到头文件”，但命令行编译完全正常，多半是IntelliSense配置和编译器的真实include路径不一致，优先检查是不是没有用CMake Tools提供的“将编译命令传给IntelliSense”功能。

5. 进阶：让项目具备更健康的工程化基因

5.1 把重复逻辑封装成CMake函数

当项目里target多了以后，你会发现每个CMakeLists都在重复做同样的事：add_library、target_include_directories、target_compile_options。与其复制粘贴十份，不如写一个函数封装起来。

比如我经常在根目录的cmake/helpers.cmake里定义：

cmake复制function(add_blur_module NAME)
    add_library(${NAME} STATIC
        ${ARGN}
    )
    target_include_directories(${NAME}
        PUBLIC
            ${CMAKE_CURRENT_SOURCE_DIR}
    )
    target_compile_options(${NAME} PRIVATE -Wall -Wextra)
endfunction()

然后在子模块里调用，一行就够：

cmake复制add_blur_module(image_decoder decoder.cpp decoder_utils.cpp)

这种封装的本意不是减少敲键盘次数，而是统一所有模块的编译标准，避免某个模块忘了加-Wall或漏了include目录。项目越大，这种“统一约束”的价值越明显。我见过很多项目中后期为了加一个编译选项，要全局搜索替换几十处，就是因为当初没有把这类逻辑收敛到一个函数里。

5.2 选项开关：同一个项目满足多种构建需求

一个实际项目通常会有不同的构建“口味”，比如要带测试、带示例、开启调试日志、使用特定第三方实现。此时就该用CMake的option机制：

cmake复制option(BLUR_TOOL_BUILD_TESTS "Build unit tests" ON)
option(BLUR_TOOL_ENABLE_LOGGING "Enable internal logging" OFF)

if(BLUR_TOOL_BUILD_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

if(BLUR_TOOL_ENABLE_LOGGING)
    target_compile_definitions(blur_tool PRIVATE BLUR_TOOL_LOG_ENABLED=1)
endif()

使用者配置的时候可以这样写：

bash复制cmake -S . -B build -DBLUR_TOOL_BUILD_TESTS=OFF -DBLUR_TOOL_ENABLE_LOGGING=ON

用option而不是直接写死add_subdirectory(tests)的好处是，下游使用方可以通过一条命令就控制整个项目的构建范围，不用去读你的CMakeLists来猜应该改哪里。很多面向第三方的库就是这么干的：默认不编示例和测试，只有你显式打开选项才编。

5.3 让库可以被安装和导出

如果你的模块未来要提供给其他项目用，除了结构清晰，还得能通过install规则把头文件和库文件装到统一目录，并导出CMake target。

通常做法是在库目标上加几条install规则：

cmake复制include(GNUInstallDirs)

install(TARGETS gaussian_blur
    EXPORT blur_toolTargets
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

install(FILES gaussian_blur.h
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/blur_tool
)

install(EXPORT blur_toolTargets
    FILE blur_toolTargets.cmake
    NAMESPACE blur_tool::
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/blur_tool
)

install加上之后，你还需要生成一个blur_toolConfig.cmake，通过它可以实现“别的项目find_package(blur_tool)就能直接用”。这个体系完整写出来又是一大篇，很多刚接触CMake的人看到这觉得复杂，容易劝退。我的建议是：如果一个模块只给自己项目内部用，不急着加install、导出这类配置，先把目录结构和target关系搞对；等真有跨项目复用需求了，再补上这部分。工程化不是为了堆新特性，而是按需演进，避免过早设计。

5.4 测试的基建要趁早

我承认“先写测试再写代码”这个习惯不是人人都能坚持，但至少从第一天就留好tests/目录和ctest入口，成本低、收益大。在根CMakeLists里写上enable_testing()，然后再往tests目录加一个子目录。每个测试文件里用简单的断言宏也行，后续再换框架。

有了ctest之后，你可以在项目根目录一条命令跑全部测试：

bash复制ctest --test-dir build --output-on-failure

这比每个人自己写个临时main函数去手动验更好维护。CMake在这一层的基建非常简单，哪怕你暂时只写了两个测试函数，也能体会到自动化测试带来的安全感。

6. 写在最后的一点体会

回顾这十几年的C++工程经验，我最想强调的其实是“把项目结构当成代码的一部分”。很多人只重视写成什么样的算法、怎么优化性能，却对组织方式缺乏敬畏，等代码量增长到一定规模，返工成本会高得让人崩溃。

CMakeLists.txt也一样，它不是一份写完就再也用不着的配置，而是一份会伴随项目成长的项目地图。你每一次增加模块、引入依赖、调整构建选项，都应该在这份地图里留下清晰的路标。先花一点时间把target关系理清楚、把include路径和链接库收拢到该在的地方，后面能帮你省回十倍的时间。

最后送上一个我排查构建问题时的土办法：当CMake报错让你完全摸不着头脑，别在一个地方死抠，先把build目录整个删掉，重新走一遍cmake -S . -B build，大概有三分之一的问题都出在脏的CMake缓存上。如果重新配置仍然不行，再回到CMakeLists里逐行检查目标依赖和路径可见性。构建系统是死的，逻辑是活的，绝大多数报错都能按照“头文件找不找得到、链接符号连不连得上、配置选项合不合理”这三个方向找到答案。