简介：围绕 CMakeLists.txt 管理大型 C++ 工程的实例包，面向需要从单文件编译过渡到多目录、多模块组织的 C++ 开发者，也适合想系统梳理 CMake 基础用法与工程结构的学习者。压缩包共 10 个文件，包含 5 个 txt 说明、3 个 cpp 源文件和 2 个 h 头文件，体积约 5KB，以精简骨架呈现顶层配置与子目录配合的构建方式。目录按应用入口、公共模块和输入输出等职责拆分，可对照理解项目初始化、子目录组织、目标编译选项与链接依赖、外部库查找、测试接入、安装配置及可选功能开关等关键写法。已有 1423 人学习，适合作为小型示例底稿，帮助读者把零散命令串成可维护的跨平台工程配置，并据此扩展自己的构建流程。资源强调模块边界与依赖关系，可作为课程设计、小项目重构或构建脚本入门的参考。
1. 从一份写到失控的构建脚本说起
接手一个三十万行的 C++ 工程时，最先出问题的往往不是业务代码，而是根目录那个已经写到一千多行的 CMakeLists.txt：谁想加一个源文件都得先读懂它，谁改错一行全组一起等编译。C++ CMakeLists 管理大型工程这件事，难点从来不是语法，而是把「全局变量式」的构建脚本改造成「目标式」的依赖图。这套方案的做法是：顶层只保留全局决策，每个模块自己声明产出什么、依赖谁、对外暴露什么，构建顺序和编译选项交给 CMake 推导。它适合两类人——正在做毕设或课程设计、需要一套能自圆其说的工程结构的学生，以及接手了历史构建脚本、想把它拆干净的在职开发者。下面从一个真实形态的目录骨架开始，把设计、实现和验收一路走完。
2. 需求拆解与目录骨架：把单体 CMakeLists 拆成三层
2.1 大型工程里构建脚本失控的四个信号
判断一份 CMakeLists 是不是到了必须重构的程度，看四个信号就够了，它们出现的顺序基本也代表了恶化的顺序。
第一个信号是全量编译时间。当改一个 .cpp 要等二十分钟，说明依赖图已经退化成「所有目标依赖所有目标」，任何改动都会触发大面积重编。第二个信号是include_directories()的调用次数，这个命令写的是目录属性，一旦在根目录写了一条覆盖全工程的路径，模块之间的边界就没了，谁也说不清某个头文件到底属于谁。第三个信号是if(WIN32)/if(APPLE)的密度，平台差异如果散落在几十个文件里，加一个新平台就是一次考古。第四个信号是那段没人敢删的注释块，通常写着「历史原因，勿动」，它背后往往是某个已经离职的人为了让 CI 过而打的补丁。
这四个信号指向同一个根因：构建配置没有归属。配置要么挂在全局变量上，要么挂在目录上，唯独没有挂在真正使用它的目标上。C++ 工程规模一旦过十万行，模块数量上到两位数，这种「无主配置」的维护成本会指数上升——这也是为什么很多团队宁可写一份 Makefile 也不愿意碰 CMake，问题不在工具，在组织方式。
2.2 顶层—模块—目标的三层目录结构
分层的第一步是把目录和职责对齐。我一般会用这样的骨架，模块数量按实际业务增减，但三层结构不变：
project/ ├── CMakeLists.txt # 顶层：全局决策 + 子目录编排 ├── cmake/ │ ├── ProjectOptions.cmake # 选项、编译选项、告警策略 │ └── toolchain-arm.cmake # 交叉编译工具链文件 ├── include/ │ └── project/ # 对外公开头文件，安装时整体导出 ├── src/ │ ├── core/ │ │ ├── CMakeLists.txt # 模块：定义 core 库目标 │ │ ├── include/project/core/ │ │ └── src/ │ ├── net/ │ │ ├── CMakeLists.txt │ │ └── src/ │ └── app/ │ ├── CMakeLists.txt # 可执行目标 │ └── main.cpp ├── tests/ │ └── CMakeLists.txt └── third_party/三层的职责边界要划清楚。顶层 CMakeLists 只做四件事：声明最低版本和工程名、引入公共配置文件、按依赖顺序add_subdirectory、定义安装导出规则。它不应该出现任何add_library或target_link_libraries，一旦出现，说明某个模块的职责漏到了顶层。模块级 CMakeLists 只关心自己这个目录产出什么目标、需要哪些源文件、依赖哪些其他目标。目标级配置则全部落在target_*系列命令上，这是整个方案的核心。
add_subdirectory的顺序有讲究。CMake 在配置阶段按书写顺序执行，如果 app 目录写在 core 前面，target_link_libraries(app PRIVATE core)会因为 core 目标尚未定义而报错。通常的做法是让被依赖的模块先出现，或者更稳妥一点，把所有库模块排在前面、可执行模块排在最后，测试目录放最末尾并用option(BUILD_TESTS)包住，这样发布构建时可以整体跳过。
2.3 target-based：所有配置都挂在目标上
target-based 这个词听起来抽象，落到代码上就是一句话：不用全局命令，只用带目标名第一参数的命令。对比一下两种写法，差距一目了然。
# 反面写法：目录级配置，作用范围靠猜 include_directories(${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR}/third_party/json/include) add_definitions(-DENABLE_LOG -DJSON_HAS_FILESYSTEM=1) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O2 -Wall") add_library(core ${CORE_SOURCES}) # 正解：目标级配置，作用范围和传播方向都是显式的 add_library(core ${CORE_SOURCES}) target_include_directories(core PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src) target_compile_definitions(core PUBLIC ENABLE_LOG PRIVATE JSON_HAS_FILESYSTEM=1) target_compile_options(core PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/W4> $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra>)两种写法的差别不在「能不能编过」，而在「改的时候能不能定位」。目录级配置一旦被多个目标共享，出问题时你只能通过make VERBOSE=1看实际命令行，反推是哪条配置生效了——这就是为什么有的人调构建问题要靠试。目标级配置则可以精确回答「这个编译选项从哪来」：它要么写在本目标的 CMakeLists 里，要么通过某个 PUBLIC 依赖传播进来，顺着target_link_libraries的链条一路查就能找到源头。
PUBLIC/PRIVATE/INTERFACE是这套机制的开关。PRIVATE表示这份配置只给本目标用，不往外传；INTERFACE表示本目标不编译任何东西、只把配置传给下游，典型用法是头文件库；PUBLIC就是两者之和。后面的章节会专门用一张表把这三种关键字的判定口径写清楚，因为这是大型工程里最容易写反、也最容易埋雷的地方。
顺带提一个容易被忽略的点：目标名本身也是接口。add_library(core ...)生成的目标名是全局的，两个子目录里各写一个core会直接报错。约定好的命名前缀（比如core、net、app）要在项目立项时就定下来，比事后加前缀便宜得多。
3. 顶层 CMakeLists 与公共配置：把全局决策收进一个入口
3.1 入口段怎么写才不留隐患
顶层文件的前二十行决定了整个工程的下限，写错这里后面全是补丁。一个可以直接抄的入口段长这样：
cmake_minimum_required(VERSION 3.20) project(project VERSION 1.4.0 DESCRIPTION "Large scale C++ project skeleton" LANGUAGES CXX C) # 默认构建类型，只在用户没指定时生效 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "Build type" FORCE) endif() set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_EXPORT_COMPILE_COMMANDS ON) set(CMAKE_POSITION_INDEPENDENT_CODE ON) include(cmake/ProjectOptions.cmake) add_subdirectory(src) if(BUILD_TESTS) enable_testing() add_subdirectory(tests) endif()逐个参数说清楚为什么这么写。cmake_minimum_required写 3.20 是因为要用target_precompile_headers和CMAKE_UNITY_BUILD这些能力，下限再低就得写兼容分支；具体数值按团队实际环境定，但一旦定下来就要写进 CI 镜像，否则「本机能编 CI 不能编」的玄学就是这么来的。project()里显式声明LANGUAGES CXX C，可以避免 CMake 去探测没装的 Fortran 编译器，也能防止某些平台上自动启用 CUDA 导致的配置变慢。
CMAKE_BUILD_TYPE那段判断是给单配置生成器（Ninja、Unix Makefiles）用的，多配置生成器（Visual Studio、Xcode）下这个变量是空的，靠CMAKE_CONFIGURATION_TYPES判断可以跳过。默认值选RelWithDebInfo是个经验值：带调试符号又开了优化，既能复现线上崩溃栈，又不会慢到没法用。CMAKE_EXPORT_COMPILE_COMMANDS打开后会生成compile_commands.json，clangd、CLion、各种静态分析工具都靠它工作，不加这一行 IDE 的跳转就会退化。
CMAKE_POSITION_INDEPENDENT_CODE设为 ON 是为了让静态库能直接链进共享库，省掉后来「静态库编不出 .so」的返工。
3.2 选项开关与编译期配置生成
大型工程一定有一堆编译期开关：要不要测、要不要打日志、日志级别多少、要不要开地址消毒。这些不能靠命令行临时传-D，得有默认值和文档，用option()声明最合适。
# cmake/ProjectOptions.cmake option(BUILD_TESTS "Build unit tests" ON) option(BUILD_SHARED "Build shared libraries instead of static" OFF) option(ENABLE_ASAN "Enable AddressSanitizer" OFF) option(ENABLE_WERROR "Treat warnings as errors" OFF) set(PROJECT_LOG_LEVEL "info" CACHE STRING "Log level: trace/debug/info/warn/error") set_property(CACHE PROJECT_LOG_LEVEL PROPERTY STRINGS trace debug info warn error) # 生成 config.h，把 CMake 侧的值落到 C++ 代码里 configure_file( ${CMAKE_CURRENT_LIST_DIR}/config.h.in ${CMAKE_BINARY_DIR}/generated/project/config.h @ONLY)config.h.in里只需要写#cmakedefine或者@VAR@占位：
/* config.h.in */ #pragma once #define PROJECT_VERSION "@PROJECT_VERSION@" #define PROJECT_LOG_LEVEL "@PROJECT_LOG_LEVEL@" #cmakedefine ENABLE_ASANconfigure_file的@ONLY参数值得单独说：不加它，CMake 会同时替换${VAR}和@VAR@两种形式，如果你的头文件里有 shell 脚本或者模板字符串含${}，就会被误替换。加上@ONLY后只认@VAR@，安全得多。生成的头文件放在CMAKE_BINARY_DIR下，通过目标级的 include 路径引进来，源码树保持干净，git status永远不会有脏文件。
元开关ENABLE_WERROR的正确用法是拿它去控制具体目标的告警选项，而不是直接改CMAKE_CXX_FLAGS。写成target_compile_options(core PRIVATE $<$<BOOL:${ENABLE_WERROR}>:-Werror>)，作用域精确，关掉时也不会留下残留。
3.3 公共接口库：把编译选项收敛到一处
当十几个模块都要加同一批告警开关和宏定义时，复制粘贴一定会漂移。标准解法是建一个不产生任何编译产物的INTERFACE库，把所有公共配置挂在它上面，然后让每个模块 PUBLIC 或 PRIVATE 链接它。
# cmake/ProjectOptions.cmake（续） add_library(project_options INTERFACE) add_library(project::options ALIAS project_options) target_compile_features(project_options INTERFACE cxx_std_17) target_compile_options(project_options INTERFACE $<$<CXX_COMPILER_ID:MSVC>:/W4 /permissive- /utf-8> $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic -Wshadow>) target_compile_definitions(project_options INTERFACE $<$<CONFIG:Debug>:PROJECT_DEBUG_BUILD=1>) if(ENABLE_ASAN AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang") target_compile_options(project_options INTERFACE -fsanitize=address -fno-omit-frame-pointer) target_link_options(project_options INTERFACE -fsanitize=address) endif()INTERFACE库不参与编译，只承载「用我的人应该拿到什么」。这里的生成器表达式负责两件事：按编译器分派参数（MSVC 用/W4，GCC/Clang 用-Wall），按构建配置分派宏（只在 Debug 下定义PROJECT_DEBUG_BUILD）。target_link_options是 CMake 3.13 之后才有的，专门传链接期参数，和编译期参数分开写，比混在CMAKE_EXE_LINKER_FLAGS里清楚。
ALIAS目标的作用是给外部消费者一个带命名空间的名字。project::options和project_options指向同一个目标，但前者在install(EXPORT)之后依然有效，后者不会出现在导出文件里。养成「内部用短名、对外用带命名空间的名字」的习惯，后面做find_package支持时能省一大截返工。
3.4 构建提速：预编译头、编译器启动器与 Unity Build
工程过十万行后，构建时间会成为日常痛点，前面这些配置里已经埋好了提速的接口，这里补充三个见效最快的。
预编译头用target_precompile_headers，粒度是目标：
target_precompile_headers(core PRIVATE <vector> <string> <memory> "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/include/project/core/export.h>")第一参数必须是目标名，PRIVATE表示这组头文件只在本目标内预编译。$<COMPILE_LANGUAGE:CXX>这个生成器表达式不能省——如果目标里混了 C 源文件，预编译头不区分语言就会在 C 编译器上炸。使用预编译头有个前提：这批头文件要足够稳定，如果天天改，预编译缓存反复失效，反而更慢。
编译器启动器解决的是「每个编译单元都要重新解析一遍头文件」的问题：
cmake -S . -B build -G Ninja \ -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \ -DCMAKE_C_COMPILER_LAUNCHER=ccacheCMAKE_CXX_COMPILER_LAUNCHER是初始化变量，必须在project()之前生效，最省事的做法就是像上面这样从命令行传。它会让每次编译调用变成ccache /usr/bin/c++ ...，命中缓存时耗时从秒级降到毫秒级。配合-G Ninja使用，Ninja 的增量判断比 Makefile 精确，大工程上差距能到两三倍。Unity Build 则是把多个 .cpp 合并成一个编译单元，用set_target_properties(core PROPERTIES UNITY_BUILD ON UNITY_BUILD_BATCH_SIZE 8)开启，适合源文件多但彼此独立的老代码，代价是出错时的报错位置会偏移，调试期建议关掉。
4. 模块级目标组织：PUBLIC/PRIVATE 与依赖传播
4.1 一个模块一个库目标
模块级 CMakeLists 的目标是「让这个目录能独立描述自己」。以 core 模块为例：
# src/core/CMakeLists.txt add_library(core src/engine.cpp src/scheduler.cpp src/logging.cpp) add_library(project::core ALIAS core) target_include_directories(core PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src) target_link_libraries(core PUBLIC project::options PRIVATE fmt::fmt Threads::Threads) set_target_properties(core PROPERTIES OUTPUT_NAME project_core VERSION ${PROJECT_VERSION} SOVERSION ${PROJECT_VERSION_MAJOR})几个细节值得展开。BUILD_INTERFACE和INSTALL_INTERFACE这组生成器表达式解决的是「同一个目标在源码树里和安装之后，头文件路径不同」的问题：构建时用绝对路径，导出到projectTargets.cmake时写相对路径include，消费方find_package之后拿到的路径会被自动拼成安装前缀下的正确位置。如果不加这层包装，导出的配置文件里会写死你本机的绝对路径，别人一用就找不到头文件。
OUTPUT_NAME和VERSION是给产物起名字、打版本号用的，SOVERSION决定共享库的 soname 主版本，这两个属性只在构建共享库时生效，静态库下写了也无害，可以先写上，将来切BUILD_SHARED时不用改。target_link_libraries里Threads::Threads来自find_package(Threads REQUIRED)，用 imported target 而不是硬编码-lpthread，跨平台时才不需要写平台分支。
4.2 PUBLIC 与 PRIVATE 的判定口径
这是大型工程里写反概率最高的一处，写反的后果往往不是立刻报错，而是等到某个下游模块用的时候才炸。判定规则只有一条：看这个依赖有没有出现在本目标的公开头文件里。
| 场景 | 关键字 | 理由 |
|---|---|---|
公开头文件#include了对方的头 | PUBLIC | 下游编译时必须能找到对方头文件 |
| 公开头文件的函数签名里出现了对方的类型 | PUBLIC | 同上，且链接期也需要 |
| 仅在 .cpp 内部使用 | PRIVATE | 下游完全不需要知道 |
| 公开头文件里的宏定义需要下游也生效 | PUBLIC（用target_compile_definitions） | 宏不传播会导致 ODR 违规 |
| 本目标只是转发，自身不编译 | INTERFACE | 头文件库、纯配置库 |
举个具体例子。core 的公开头文件里有std::shared_ptr<Engine>，那<memory>只是标准库，不需要额外链接；但如果它暴露了fmt::format_string作为参数类型，fmt就必须是 PUBLIC，否则任何 include 了 core 头文件的模块都编不过，报错信息还是「找不到 fmt/core.h」，看起来像是路径问题，实际是依赖传播没做对。
反过来，把Threads::Threads写成 PUBLIC 也不会立刻出错，但会让所有下游目标凭空多出一条链接依赖，在静态链接场景下可能引入意料之外的符号，排查起来极其费劲。用cmake --build build --verbose看链接命令行，多出来的-lpthread就是这么来的。血泪经验是：默认写 PRIVATE，只有编译报「找不到头文件」时才改成 PUBLIC，这个方向比反过来安全。
target_link_libraries里还可以带作用域限定符做更细的控制：
target_link_libraries(net PUBLIC project::core PRIVATE $<$<PLATFORM_ID:Linux>:dl> $<$<PLATFORM_ID:Windows>:ws2_32>)syntax $<$<PLATFORM_ID:...>:...>让平台相关的库只在对应平台上参与链接，比在外面套if(WIN32)干净，而且这些表达式会被完整写进导出文件，消费方在别的平台find_package时也能正确求值。
4.3 安装导出：让别的工程能 find_package 到你
一个「大型工程」和「一个大项目」的区别，在于前者会被别人依赖。导出规则的写法有固定套路：
include(GNUInstallDirs) include(CMakePackageConfigHelpers) install(TARGETS core net EXPORT projectTargets ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) install(DIRECTORY include/project DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) install(EXPORT projectTargets FILE projectTargets.cmake NAMESPACE project:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/project) configure_package_config_file( cmake/projectConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/projectConfig.cmake INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/project) write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/projectConfigVersion.cmake VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/projectConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/projectConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/project)INCLUDES DESTINATION这一行容易被漏掉，作用是给导出目标自动补上INTERFACE_INCLUDE_DIRECTORIES，漏了它，消费方 link 之后依然找不到头文件。NAMESPACE project::让导出文件里的目标名变成project::core，和源码树里的 ALIAS 保持一致，消费方从源码构建和从安装包构建的写法完全相同，这一点在联调阶段非常省事。SameMajorVersion是版本兼容策略，主版本相同即认为兼容，对应语义化版本；如果你的库在次版本里加过不兼容改动，就换成SameMinorVersion。
4.4 第三方依赖的接入策略
第三方依赖就两种接法，选错了后面全是麻烦。系统里已经广泛安装的（zlib、OpenSSL、Boost）用find_package，让发行版或包管理器负责版本；项目强依赖且版本敏感的（序列化库、格式化库）用FetchContent锁定源码。
include(FetchContent) set(FETCHCONTENT_QUIET OFF) FetchContent_Declare(fmt GIT_REPOSITORY https://example.invalid/fmtlib/fmt.git GIT_TAG 10.1.1 GIT_SHALLOW TRUE SYSTEM) FetchContent_MakeAvailable(fmt) find_package(Threads REQUIRED)GIT_TAG写具体版本号而不是master，是保证构建可复现的前提；GIT_SHALLOW TRUE只拉最近一次提交，能显著缩短首次配置时间；SYSTEM会把该依赖的头文件标记为系统头，从而屏蔽它自己的告警，不然第三方库的告警会淹没你自己的。FETCHCONTENT_QUIET OFF建议调试期打开，能看到拉取进度，出问题时知道卡在哪。
一个折中做法是「优先 find_package，找不到再 FetchContent」：先find_package(fmt 10 QUIET)，如果fmt_FOUND为假再走 FetchContent。这样在已经有预编译包的 CI 上能省掉拉源码的时间，在干净环境里也能自己下载。代价是不同机器可能用到不同版本的 fmt，所以版本约束要写死，并且定期对齐。
5. 避坑与排查：五类高频翻车现场
5.1 改了公共头文件，下游行为没变化
现象：修改 core 的头文件后重新构建，net 模块的运行结果还是旧的，有时候还会在链接阶段报undefined reference。
原因：两个模块之间只写了include_directories或者target_include_directories各自的路径，没有用target_link_libraries建立目标级依赖。CMake 的构建图里 core 和 net 是两个互不相干的节点，Ninja 只知道「net 的源文件变了要重编」，不知道「core 的头文件变了 net 也要重编」。预编译头和 Unity Build 会进一步削弱编译器的头文件依赖扫描，让问题更难发现。
解决：所有跨模块引用都走target_link_libraries，头文件路径由PUBLIC/INTERFACE自动传播，不要在两边的 CMakeLists 里各写一遍路径。改完之后用cmake --graphviz=deps.dot build生成依赖图，肉眼确认上下游关系存在。
5.2 命令行传的编译选项「不生效」
现象：CI 上用-DCMAKE_CXX_FLAGS=-fno-exceptions传的选项，本地构建正常，CI 上某些模块却还是允许异常。
原因：set(CMAKE_CXX_FLAGS "...")创建的是普通变量，作用域是当前目录及其子目录，并且会遮蔽命令行传入的同名 cache 变量。只要某个子目录的 CMakeLists 里出现过一次这种写法，那条命令及其所有子目录就都看不到-D传进来的值了，而兄弟目录不受影响——于是表现为「部分模块生效」。
解决：彻底不用CMAKE_CXX_FLAGS，改为在project_options接口库上用target_compile_options统一挂，或者用add_compile_options并明确它的目录作用域。排查时执行grep -rn "CMAKE_CXX_FLAGS" --include=CMakeLists.txt .，把结果清零。
5.3 头文件里暴露的类型，链接时写成 PRIVATE
现象：下游模块 include 了 core 的头文件，编译时报「找不到 xxx 的定义」，或者链接时报某个符号 undefined，但 core 自己编得好好的。
原因：core 的公开头文件在函数签名里用了某个第三方库的类型（比如std::unique_ptr<Impl>用了前向声明没问题，但SomeThirdPartyType作为参数就不行），而这个第三方库在 core 里是 PRIVATE 链接的。PRIVATE 意味着不向下游传播 include 路径和链接项，下游自然拿不到。
解决：按 4.2 那张表重新判定。判定技巧是看头文件里有没有出现这个名字——出现了就必须 PUBLIC。反过来，只在 .cpp 里用的依赖一律 PRIVATE，别图省事全写 PUBLIC，那会让所有下游目标的链接命令行无限膨胀。用cmake --build build --verbose对比改动前后 net 目标的链接命令，多出来的库就是漏网的 PRIVATE。
5.4 Debug 链接 Release 库导致的诡异崩溃
现象：Debug 构建下程序在 STL 迭代器处断言失败，或者std::string析构时堆损坏，改成 Release 就一切正常。
原因：MSVC 下 Debug 和 Release 的迭代器调试级别（_ITERATOR_DEBUG_LEVEL）和 CRT 版本不同，混链必然内存布局不一致。多配置生成器下，install出来的库默认只有一种配置，find_package拿到的是 Release 版，却被 Debug 目标链接了。CMake 本身不会报错，因为符号名在链接期是兼容的。
解决：给 Debug 产物加后缀，set_target_properties(core PROPERTIES DEBUG_POSTFIX "d")，安装时两个配置分别落到不同文件名；消费方用 imported target 的配置映射（IMPORTED_LOCATION_DEBUG/IMPORTED_LOCATION_RELEASE），让 CMake 按当前配置选正确的库。验收时在 Debug 和 Release 下各跑一遍完整测试，这一步不能省。
5.5 本机能编，CI 上 find_package 找不到
现象：本地开发机一切正常，推到 CI 后配置阶段就失败，报某个依赖的Config.cmake找不到。
原因：本地依赖是手动装到/usr/local或者通过包管理器装的，CMake 的默认搜索路径里正好有；CI 镜像是干净的，没有这个包。更隐蔽的情况是本地装的是 3.x 版本、CI 缓存里是 2.x，配置能过但编译报「没有成员函数」。
解决：两条路选一条走到底。要么用 FetchContent 拉源码，版本锁在GIT_TAG，完全不依赖环境；要么在 CI 镜像的 Dockerfile 里显式装好并锁定版本。不要两边混用。另外，find_package时把版本号写进参数（find_package(fmt 10 REQUIRED)），让版本不匹配在配置阶段就失败，而不是拖到编译阶段才暴露。
6. 验收与答辩：怎么证明这套构建体系是可靠的
构建体系的验收和自我检验，核心是「换一台干净机器能不能复现」。我在交付前会固定跑一遍下面这套动作，五步全过才算完：
#!/usr/bin/env bash set -euo pipefail # 1. 干净的 out-of-source 构建 rm -rf build stage cmake -S . -B build -G Ninja \ -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DCMAKE_INSTALL_PREFIX="$PWD/stage" # 2. 全量编译并记录耗时，作为基线 /usr/bin/time -f "full build: %e s" cmake --build build -j"$(nproc)" # 3. 增量构建：碰一个私有源文件，应只重编该模块 touch src/net/src/connection.cpp cmake --build build -j"$(nproc)" 2>&1 | grep -c "Building CXX" # 4. 安装并按 find_package 方式消费 cmake --install build cmake -S tests/consumer -B consumer-build -DCMAKE_PREFIX_PATH="$PWD/stage" cmake --build consumer-build # 5. 测试 ctest --test-dir build --output-on-failure第 3 步是很多人会漏掉的：grep -c "Building CXX"的输出应该是 1 或者很小的数字。如果碰到一个 .cpp 却重编了整个工程，说明依赖图里有隐式的全局依赖，回去查include_directories和全局add_definitions。第 4 步用独立的 consumer 工程去find_package，验证的是导出文件是否自洽——这一步过不了，说明INSTALL_INTERFACE或者INCLUDES DESTINATION写漏了。第 2 步的耗时记下来存进仓库文档，每次重构后对比，构建时间涨了 30% 以上就该查是不是有人偷偷加了全局依赖。
验收清单可以整理成一张表，答辩时直接投屏：
| 验收项 | 合格标准 | 检查方式 |
|---|---|---|
| 干净构建 | 全新目录一次配置成功，零 warning | 删除 build 目录重跑 |
| 增量构建 | 改单文件只重编所属模块 | 步骤 3 的计数 |
| 安装导出 | 独立工程能 find_package 并链接 | 步骤 4 的 consumer |
| 跨配置 | Debug/Release 各自可编可测 | -DCMAKE_BUILD_TYPE=Debug再跑一遍 |
| 依赖可复现 | 无本地绝对路径，第三方版本锁定 | grep -r "/home|/Users" build/*.cmake |
| 选项生效 | 命令行传的 flags 出现在所有目标 | --verbose抽查三个模块 |
答辩环节，构建相关的提问基本集中在两点：为什么这么分层、PUBLIC/PRIVATE 怎么判断。前一个问题回答「模块自治、顶层只做编排」；后一个问题直接背出 4.2 的那条规则——公开头文件里出现就 PUBLIC，否则 PRIVATE，再补一句「写反的代价是下游链接错误，排查成本高」。如果有人追问性能，就讲预编译头和 ccache 的组合，以及 Unity Build 的适用边界。这些都是能当场演示的，比空谈架构有说服力。
从那以后我每次开新工程，第一件事就是把这份顶层 CMakeLists 和ProjectOptions.cmake抄进去，先跑通 clean build + install + consumer 三步，再开始写业务代码。这个习惯让我少返工过很多次——构建脚本的债，越晚还越贵。希望帮到你。
本文还有配套的精品资源，点击获取
