1. 从单目录到多目录：为什么CMake工程迟早要迈过这道坎
刚开始写C++的时候，几乎所有人都是从单目录起步的。一个main.cpp，一个CMakeLists.txt，三五行配置就能跑起来，编译、链接、运行一气呵成。这种体验很爽，但它的生命周期通常不会太长。只要项目稍微长大一点——比如你开始把工具函数拆出去、把业务逻辑独立成模块、把第三方依赖单独放一层——单目录结构就会迅速变成一锅粥：头文件满天飞，源文件互相#include，改一个函数要重新编译整个工程，链接错误一个接一个。
我见过不少项目卡在这个阶段：代码能跑，但没人敢动构建脚本，因为一改就崩。问题的根源往往不是CMake本身难，而是目录结构没有和构建逻辑对齐。单目录工程里，编译器默认把当前目录当作头文件搜索路径，所有.cpp一股脑塞进一个可执行文件，依赖关系是隐式的、靠约定维持的。一旦拆成多目录，这些隐式约定全部失效，你必须显式地告诉CMake：头文件在哪、源文件怎么组织、模块之间谁依赖谁、产物输出到哪里。
这篇内容就是围绕"CMake构建工程-cpp多目录"这个主题，把从单目录迁移到多目录的完整思路、目录划分原则、CMakeLists.txt的写法、常见报错的排查链路，以及我踩过的那些坑，一次性讲透。适合已经会写最基础CMakeLists.txt、但一遇到多目录就发怵的开发者；也适合正在重构老项目、想把构建系统理顺的人。读完之后，你应该能独立设计一个结构清晰、可扩展、编译效率合理的多目录C++工程。
先说一个反直觉的结论：多目录工程的核心难点不在CMake语法，而在"边界划分"。你把哪些代码归为一个模块、模块对外暴露什么头文件、模块之间是静态库还是动态库、公共依赖放在哪一层——这些决策一旦定错，后面写再多CMake命令都是打补丁。所以下面我会先讲结构设计，再讲具体写法，最后讲排错。
2. 多目录工程的目录划分：先想清楚边界，再动手写CMake
2.1 一个能长期维护的典型目录骨架
在动手写任何CMakeLists.txt之前，我习惯先把目录画出来。下面这个结构是我在多个中型C++项目里反复验证过的，兼顾清晰度和扩展性：
project_root/ ├── CMakeLists.txt # 顶层，负责全局配置和子目录调度 ├── cmake/ # 自定义CMake模块（如FindXXX.cmake） ├── include/ # 对外公开的头文件（可选，视项目而定） ├── src/ │ ├── CMakeLists.txt │ ├── main.cpp │ ├── core/ # 核心模块 │ │ ├── CMakeLists.txt │ │ ├── include/core/ │ │ │ └── engine.h │ │ └── src/ │ │ └── engine.cpp │ ├── utils/ # 工具模块 │ │ ├── CMakeLists.txt │ │ ├── include/utils/ │ │ │ └── string_helper.h │ │ └── src/ │ │ └── string_helper.cpp │ └── app/ # 应用层，组装各模块 │ ├── CMakeLists.txt │ └── main.cpp ├── third_party/ # 第三方依赖 └── tests/ # 单元测试 └── CMakeLists.txt这个结构有几个关键设计点，值得逐个说清楚。
每个模块自带include/和src/，而不是把所有头文件集中到顶层include/。这样做的好处是模块自包含：core模块的头文件放在core/include/core/下，其他模块引用时写#include "core/engine.h"，路径里带模块名，一眼就能看出依赖来源。如果所有头文件都堆在顶层include/，时间一长你根本分不清哪个头属于哪个模块，删除模块时也容易漏掉。
模块名作为头文件路径的一级目录，比如core/include/core/engine.h。这是为了避免头文件名冲突。两个模块都有config.h是常有的事，加上模块前缀后，core/config.h和utils/config.h泾渭分明。这个约定在大型项目里几乎是标配。
顶层CMakeLists.txt只做三件事：设置全局编译选项、声明项目、add_subdirectory调度子目录。它不应该包含任何具体的源文件编译逻辑。很多人喜欢把add_executable写在顶层，结果子目录的库还没定义就引用了，顺序一乱就报错。
2.2 模块边界怎么定：按"变化频率"而不是"文件类型"划分
新手最容易犯的错，是按文件类型划分目录：把所有.h放include/，所有.cpp放src/，所有工具函数放utils/。这种划分在项目初期看着整齐，但很快会失控——因为"工具函数"是个无底洞，什么都能往里塞，最后utils变成垃圾堆，谁都不敢改。
我的经验是按变化频率和职责划分模块。变化频率相近、职责内聚的代码放一起。比如：
core：核心业务逻辑，变化频率中等，被多个模块依赖。utils：纯函数工具，几乎不变，无业务依赖，可以被任何模块引用。app：应用组装层，变化频率最高，只依赖其他模块，不被依赖。network、storage、render等：按具体职责拆分的功能模块。
这样划分之后，依赖关系是单向的：app依赖core和utils，core依赖utils，utils不依赖任何人。单向依赖是构建系统稳定的前提，一旦出现循环依赖（core依赖utils，utils又依赖core），CMake的库链接顺序就会变成噩梦。
提示：判断模块边界是否合理，有个简单方法——如果删除某个模块，需要改动的
#include是否集中在少数几个文件里？如果是，边界清晰；如果牵一发动全身，说明模块划分有问题。
2.3 头文件可见性：public和private要分开
多目录工程里，头文件分两类：对外暴露的public头文件和模块内部使用的private头文件。前者会被其他模块#include，后者只在模块内部用。
在上面的结构里，core/include/core/放public头文件，core/src/里可以放private头文件（比如engine_impl.h）。CMake里通过target_include_directories的PUBLIC和PRIVATE关键字来区分：
target_include_directories(core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src )PUBLIC意味着依赖core的目标也能看到这个路径，PRIVATE则只有core自己能看到。这个区分非常重要：它把"模块对外契约"和"内部实现细节"隔离开，其他模块无法误引用你的内部头文件，重构时你就能放心大胆地改内部实现。
我见过太多项目把所有头文件路径都设成PUBLIC，结果内部实现头文件被外部引用，想改都改不动。这个坑一定要在项目早期避开。
3. 顶层CMakeLists.txt的写法：全局配置与子目录调度
3.1 版本声明和项目定义的门道
顶层CMakeLists.txt的第一行通常是cmake_minimum_required。这个命令不只是声明最低版本，它还决定了CMake的策略行为——不同版本对同一命令的默认处理可能不同。写低了，新特性用不了；写高了，老环境跑不起来。
cmake_minimum_required(VERSION 3.16) project(MyMultiDirProject VERSION 1.0.0 DESCRIPTION "A multi-directory C++ project" LANGUAGES CXX )我一般把最低版本定在3.16，原因是这个版本对target_link_libraries的PRIVATE/PUBLIC/INTERFACE语义支持完整，且FetchContent等现代特性可用。如果你的目标环境更老，可以降到3.10，但要注意某些命令的行为差异。
project()命令里的LANGUAGES CXX明确声明只用C++，避免CMake去探测C编译器，能省一点配置时间。VERSION字段定义后，可以在代码里通过PROJECT_VERSION变量使用，方便做版本号管理。
3.2 全局编译选项：别在每个子目录里重复设置
编译选项（如C++标准、警告级别、优化等级）应该在顶层统一设置，而不是散落在各个子目录。散落设置的后果是：某个模块用了C++17，另一个用了C++14，链接时ABI不兼容，报出一堆莫名其妙的符号错误。
set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) if(MSVC) add_compile_options(/W4 /permissive-) else() add_compile_options(-Wall -Wextra -Wpedantic) endif()CMAKE_CXX_EXTENSIONS OFF这个设置容易被忽略。它关闭编译器对C++标准的扩展（比如GCC的-std=gnu++17变成-std=c++17），保证代码在不同编译器上行为一致。如果你的代码用了typeof、变长数组这类GNU扩展，关掉之后会编译失败——但这恰恰是好事，逼你写标准C++。
add_compile_options会影响之后定义的所有目标。注意它的作用域：在顶层调用，影响所有子目录；在子目录调用，只影响该子目录及之后。所以全局选项放顶层，模块特有的选项放模块自己的CMakeLists.txt。
3.3 add_subdirectory的顺序不是随便排的
顶层最后用add_subdirectory把子目录拉进来：
add_subdirectory(src/utils) add_subdirectory(src/core) add_subdirectory(src/app)顺序有讲究：被依赖的模块先添加。因为add_subdirectory是顺序执行的，当core的CMakeLists.txt里写target_link_libraries(core PUBLIC utils)时，utils目标必须已经存在。如果顺序反了，CMake会报"target utils not found"。
这个规则在依赖层级深的时候尤其重要。我一般按依赖拓扑排序：最底层的utils最先，中间的core其次，最上层的app最后。如果模块多了记不住顺序，可以画个依赖图贴在CMakeLists.txt旁边。
注意：
add_subdirectory的路径是相对于当前CMakeLists.txt所在目录的。顶层写add_subdirectory(src/utils)，指的是project_root/src/utils/。子目录里再写add_subdirectory，路径相对子目录，别搞混。
3.4 输出目录统一管理
默认情况下，CMake把可执行文件和库文件散落在各个子目录的构建目录里，找起来很烦。我习惯在顶层统一指定输出路径：
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)这样所有可执行文件进bin/，所有库文件进lib/，构建产物一目了然。多配置生成器（如Visual Studio）会自动在每个配置下再建子目录，不用额外处理。
4. 子目录CMakeLists.txt：库目标怎么定义、依赖怎么连
4.1 用add_library把模块编译成库
每个功能模块的CMakeLists.txt核心任务是定义一个库目标。以core模块为例：
# src/core/CMakeLists.txt add_library(core STATIC src/engine.cpp src/parser.cpp ) target_include_directories(core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ) target_link_libraries(core PUBLIC utils )这里有几个决策点值得展开。
STATIC还是SHARED？静态库（STATIC）在链接时把代码复制进最终可执行文件，部署简单，没有运行时库路径问题；动态库（SHARED）多个程序共享一份代码，节省内存，但部署时要带上.so/.dll。对于内部模块，我默认用STATIC，除非有明确的共享需求。原因是静态库的链接行为更可预测，不会出现"运行时找不到符号"的问题。
源文件列表要不要用变量？很多人喜欢file(GLOB ...)自动收集源文件：
file(GLOB CORE_SOURCES "src/*.cpp") add_library(core STATIC ${CORE_SOURCES})我不推荐这么做。GLOB在配置阶段执行，新增源文件后如果不重新运行CMake配置，新文件不会被编译，容易造成"我明明加了文件怎么没生效"的困惑。显式列出源文件虽然啰嗦，但行为确定，且改动时diff清晰。如果源文件确实多，可以用变量分组，但别用GLOB。
target_include_directories的PUBLIC/PRIVATE，前面讲过，这里再强调一次：PUBLIC路径会传递给依赖方，PRIVATE不会。core的public头文件在include/下，所以include/是PUBLIC；内部头文件在src/下，是PRIVATE。这个区分让core的内部实现对外完全隐藏。
4.2 target_link_libraries的传递性：PUBLIC、PRIVATE、INTERFACE
target_link_libraries的三个关键字是CMake现代用法的精髓，也是最容易用错的地方。
PRIVATE：依赖只用于当前目标的实现，不传递给依赖方。PUBLIC：依赖既用于当前目标，也传递给依赖方。INTERFACE：依赖不用于当前目标，只传递给依赖方（常用于header-only库）。
举个例子：core在实现里用了utils的函数，且core的public头文件里也#include了utils的头文件。这种情况下必须用PUBLIC，因为依赖core的app在编译时也需要找到utils的头文件。
如果core只在.cpp里用utils，public头文件不暴露utils，那就用PRIVATE。这样app不会被动继承utils的依赖，依赖关系更干净。
# core只在实现里用utils，public头文件不暴露 target_link_libraries(core PRIVATE utils) # core的public头文件暴露了utils的类型 target_link_libraries(core PUBLIC utils)用错关键字的典型症状：编译时报"找不到头文件"（该PUBLIC的用了PRIVATE），或者链接时报"未定义符号"（该传递的依赖没传递）。排查这类问题时，先检查target_link_libraries的关键字。
4.3 可执行目标：app模块怎么组装
app模块负责把各模块组装成最终可执行文件：
# src/app/CMakeLists.txt add_executable(myapp main.cpp ) target_link_libraries(myapp PRIVATE core utils )app依赖core和utils，用PRIVATE因为可执行文件不被其他目标依赖。注意这里不需要再写target_include_directories——core和utils的PUBLIC包含路径会自动传递给myapp，这就是现代CMake的"用法需求"（usage requirements）机制。你只要正确设置了库的PUBLIC路径，使用方就自动获得，不用手动重复。
这个机制是多目录工程能保持简洁的关键。老式CMake里到处写include_directories和link_directories，全局污染严重；现代CMake用目标属性传递，依赖关系清晰可控。
4.4 一个完整的子目录示例：utils模块
把上面的模式套到utils模块：
# src/utils/CMakeLists.txt add_library(utils STATIC src/string_helper.cpp src/file_helper.cpp ) target_include_directories(utils PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include ) # utils不依赖任何其他模块utils是最底层模块，没有target_link_libraries。它的public头文件在include/utils/下，其他模块通过#include "utils/string_helper.h"引用。
5. 编译链接报错排查：多目录工程最常见的五类问题
多目录工程的报错，八成集中在头文件找不到、符号未定义、循环依赖、重复定义、链接顺序这五类。下面按排查链路逐个说。
5.1 "fatal error: xxx.h: No such file or directory"
这是最高频的报错。原因通常是target_include_directories没设对，或者设了但没传递到使用方。
排查步骤：
- 确认头文件实际路径。比如
core/include/core/engine.h，那么包含路径应该是core/include，代码里写#include "core/engine.h"。 - 确认
target_include_directories写的是core/include而不是core/include/core。多写一层或少写一层都会导致找不到。 - 确认使用方通过
target_link_libraries链接了core，且core的包含路径是PUBLIC。如果是PRIVATE，使用方看不到。
我踩过的一个坑：把target_include_directories写在add_library之前。CMake允许这样，但目标还不存在，命令会报错。正确顺序是先add_library定义目标，再设置属性。
5.2 "undefined reference to xxx"
链接期报错，说明编译通过了（头文件找到了），但链接时找不到函数实现。常见原因：
- 源文件没加入
add_library/add_executable的源文件列表。检查模块的CMakeLists.txt是否漏了某个.cpp。 - 库之间的依赖没连上。比如
core用了utils的函数，但target_link_libraries(core ...)里没写utils。 - 函数声明和定义签名不一致。比如头文件里是
void foo(int)，实现里是void foo(long)，编译不报错但链接找不到。
排查时先看报错的符号属于哪个模块，然后检查该模块的源文件列表和依赖声明。
5.3 循环依赖：CMake配置阶段的死锁
如果core依赖utils，utils又依赖core，CMake在配置阶段可能报错，或者链接时出现奇怪的符号问题。循环依赖的本质是设计问题，不是CMake能解决的。
解决办法是提取公共部分。如果core和utils互相依赖，说明它们之间有共享的代码，把这部分抽成第三个模块common，让core和utils都依赖common，打破循环。
# 打破循环依赖 add_library(common STATIC ...) target_link_libraries(core PUBLIC common) target_link_libraries(utils PUBLIC common)5.4 重复定义：同一个符号出现在多个目标里
如果两个库都定义了同一个全局函数或变量，链接时会报"multiple definition"。这通常是因为公共代码被复制到了多个模块，或者头文件里定义了非inline的全局变量。
排查方法：用nm命令查看库文件里的符号：
nm -C libcore.a | grep "T your_symbol" nm -C libutils.a | grep "T your_symbol"如果两个库都有，说明重复了。解决办法是把公共定义移到单独模块，或者用inline、匿名命名空间限制作用域。
5.5 链接顺序问题：静态库的依赖顺序
静态库链接时，链接器从左到右扫描，遇到未定义符号时会在后面的库里找。如果顺序不对，比如app链接core和utils，但core依赖utils，写成：
target_link_libraries(myapp PRIVATE core utils) # 可能出错链接器先扫core，发现它引用了utils的符号，但此时utils还没扫到，符号未解析；等扫到utils时，core已经处理完了，不会回头再解析。正确顺序是依赖方在前，被依赖方在后：
target_link_libraries(myapp PRIVATE core utils) # core在前，utils在后不过现代CMake的target_link_libraries会自动处理传递依赖的顺序，只要你正确声明了core依赖utils，myapp链接core时CMake会自动把utils排在后面。所以正确声明模块间依赖，比手动调整链接顺序更可靠。
6. 进阶技巧：让多目录工程编译更快、结构更稳
6.1 用target_compile_definitions传递宏定义
模块间有时需要传递编译宏，比如core需要知道utils是否开启了某个特性。用target_compile_definitions：
target_compile_definitions(utils PUBLIC UTILS_HAS_LOGGING=1 )PUBLIC意味着依赖utils的目标也会获得这个宏定义。这样core在代码里可以用#if UTILS_HAS_LOGGING做条件编译，而不用手动在多个CMakeLists.txt里重复定义。
6.2 预编译头文件加速编译
多目录工程编译慢，很大一部分时间花在重复解析公共头文件上。预编译头（PCH）能显著加速：
target_precompile_headers(core PRIVATE <vector> <string> <memory> )把常用的标准库头文件放进PCH，编译时只解析一次。注意PCH里的头文件应该是稳定的、不常变的，否则每次改动都会触发全量重编译。
6.3 用CMakePresets.json管理构建配置
多目录工程通常有多种构建配置：Debug、Release、不同编译器、不同平台。用CMakePresets.json把这些配置固化下来，团队成员和CI用同一套预设，避免"在我机器上能编译"的问题。
{ "version": 3, "configurePresets": [ { "name": "debug", "generator": "Ninja", "binaryDir": "${sourceDir}/build/debug", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", "CMAKE_CXX_STANDARD": "17" } }, { "name": "release", "inherits": "debug", "binaryDir": "${sourceDir}/build/release", "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } } ] }用的时候直接cmake --preset debug，不用记一长串参数。
6.4 依赖关系可视化
模块多了之后，依赖关系容易乱。CMake可以生成依赖图：
cmake --graphviz=deps.dot . dot -Tpng deps.dot -o deps.png生成的图能直观看出哪些模块依赖哪些模块，有没有意外的依赖或循环。我一般在重构模块边界时跑一次，确认依赖方向符合预期。
6.5 单元测试目录的接入
tests/目录通常用enable_testing()和add_test()接入：
# tests/CMakeLists.txt add_executable(test_core test_engine.cpp ) target_link_libraries(test_core PRIVATE core) add_test(NAME test_core COMMAND test_core)顶层CMakeLists.txt里加enable_testing()，然后add_subdirectory(tests)。测试目标链接被测模块，复用同样的包含路径和依赖，不用重复配置。
7. 我在多目录工程里踩过的几个真实坑
第一个坑是头文件路径写绝对路径。早期我图省事，target_include_directories里写了/home/user/project/core/include，本地编译没问题，换台机器就崩。正确做法是用${CMAKE_CURRENT_SOURCE_DIR}或${CMAKE_SOURCE_DIR}拼相对路径，保证可移植。
第二个坑是在子目录里用include_directories而不是target_include_directories。include_directories是目录级命令，影响该目录及所有子目录的所有目标，污染范围大。现代CMake应该用target_include_directories，精确控制到目标级别。我重构老项目时，把include_directories全部替换成target_include_directories，依赖关系一下子清晰了。
第三个坑是忘记add_subdirectory的顺序。有次新增一个模块，CMakeLists.txt写好了但忘了在顶层加add_subdirectory，编译时一直报"target not found"，查了半天才发现是漏了一行。后来我养成了习惯：新增模块时，先改顶层CMakeLists.txt，再写模块自己的配置。
第四个坑是静态库的PUBLIC头文件路径没设对。core的public头文件在include/core/下，我一开始把包含路径设成了include/core，结果使用方写#include "core/engine.h"时找不到——因为路径应该是include，代码里才带core/前缀。这个前缀约定一定要和包含路径对齐。
第五个坑是Debug和Release混用。有次链接一个第三方库，它是Release编译的，我的工程是Debug，链接时报了一堆运行时库不匹配的错误。多目录工程里，所有模块的构建类型必须一致，第三方库也要匹配。用CMakePresets.json固定构建类型能避免这个问题。
8. 从多目录再往前走：什么时候该考虑更重的构建方案
多目录CMake工程能撑到中等规模，大概几十个模块、几十万行代码。再往上，你会遇到新的瓶颈：全量编译太慢、依赖管理复杂、跨平台配置繁琐。这时候可以考虑：
- 模块化+按需编译：把不常变的模块编译成预编译库，只重编译改动的模块。
- 分布式编译：用编译缓存工具（如ccache）或分布式编译方案加速。
- 包管理：用Conan、vcpkg等管理第三方依赖，避免手动维护
third_party/。 - 构建系统生成器：用CMake生成Ninja构建文件，比Make快不少。
但这些都是在多目录结构理顺之后才需要考虑的。如果目录划分和依赖关系还是一团乱麻，上再重的工具也是治标不治本。我个人的经验是：先把多目录CMake写扎实，把模块边界和依赖方向定清楚，后面无论换什么工具，迁移成本都可控。
最后分享一个我一直在用的小习惯：在每个模块的CMakeLists.txt顶部写一行注释，说明这个模块的职责和它依赖的模块。比如：
# core: 核心业务逻辑，依赖 utils，被 app 依赖模块多了之后，这行注释比任何文档都管用，新人接手时一眼就能看懂依赖关系。构建系统是工程的骨架，骨架正了，后面加多少肌肉都不会塌。
