FetchContent_Declare仅注册下载任务，必须调用FetchContent_MakeAvailable才能触发下载、解压、配置和构建；否则会导致target未找到、头文件缺失等问题。
FetchContent_Declare 之后必须调用 FetchContent_MakeAvailable
很多人写完 FetchContent_Declare 就以为依赖拉下来了，结果编译时报 target not found 或头文件找不到。其实 FetchContent_Declare 只是注册下载任务，真正触发下载、解压、配置和构建的是 FetchContent_MakeAvailable。
常见错误现象：
-
add_subdirectory找不到目标目录（因为没执行MakeAvailable） - CMake configure 阶段不报错，但 generate 阶段失败
- 依赖的
INTERFACE_INCLUDE_DIRECTORIES没生效
正确顺序必须是：
FetchContent_Declare( fmt GIT_REPOSITORY https://github.com/fmtlib/fmt.git GIT_TAG 10.2.1 ) FetchContent_MakeAvailable(fmt)
注意：不能把 MakeAvailable 放在 project() 之前，否则部分变量（如 CMAKE_CXX_STANDARD）还没初始化，依赖可能以 C++98 构建。
立即学习“C++免费学习笔记（深入）”；
第三方库用 add_subdirectory 还是 find_package？
FetchContent 默认走 add_subdirectory 路径——它把源码当成本地子项目集成进来，不是找系统已安装的库。这意味着：
- 你控制全部构建参数（比如强制
CMAKE_CXX_STANDARD 20），不会受系统fmt版本限制 - 但也会继承它的
add_library方式：如果对方用add_library(fmt INTERFACE)，你直接target_link_libraries(myapp PRIVATE fmt)就行；如果它用add_library(fmt STATIC)，你得确保链接时能找到符号，且没有 ODR 冲突 - 不支持
find_package(fmt CONFIG)的自动导入逻辑（除非该库自己提供fmtConfig.cmake并在MakeAvailable后导出）
所以别在 FetchContent_MakeAvailable(fmt) 后写 find_package(fmt)——大概率失败，CMake 根本没把路径加进 CMAKE_PREFIX_PATH。
如何避免重复下载和反复 configure？
默认情况下，每次 cmake .. 都会检查 Git tag 是否变化，即使本地已有，也可能触发重新 fetch。这不是 bug，是 FetchContent 的设计行为。
实操建议：
- 用
FETCHCONTENT_FULLY_DISCONNECTED ON关闭自动更新（适合 CI 或锁定版本场景） - 把依赖缓存到统一目录，比如设
-DFETCHCONTENT_BASE_DIR=/path/to/3rdparty，避免不同项目各自 clone 一份 - 对 Git 依赖，优先用
GIT_TAG而非GIT_SHALLOW TRUE+GIT_SUBMODULES组合——后者容易因 submodule URL 权限或网络问题中断 - 如果依赖本身也用 FetchContent（比如 A 依赖 B，B 又依赖 C），确保顶层项目显式声明所有间接依赖，否则 C 可能被跳过
性能影响：首次 configure 可能卡住 10–60 秒（尤其大库如 LLVM），但后续只要没改 GIT_TAG，就只做轻量校验。
跨平台时 Windows 和 macOS 的路径/大小写陷阱
FetchContent 在 Windows 上默认用 Git Bash 或 cmd 下载，解压后路径名大小写敏感性跟宿主系统一致。问题常出现在：
- Git 仓库里文件名只有大小写差异（如
Utils.h和utils.h），Windows 下解压会冲突，CMake 报file already exists - macOS 默认 HFS+ 是大小写不敏感文件系统，但某些 CI（如 GitHub Actions macOS runner）启用了 APFS 大小写敏感卷，导致同一份
FetchContent_Declare在本地能过、CI 上失败 - 某些库的 CMakeLists.txt 里硬编码了
include_directories(./src)，而 FetchContent 解压后实际路径是fetchcontent/src，相对路径失效
应对方式：
- 加
UPDATE_DISCONNECTED ON并手动维护一份干净的 vendor 快照（适合对稳定性要求高的项目） - 用
FETCHCONTENT_SOURCE_DIR_fmt等变量显式指定解压路径，再通过set_property(DIRECTORY PROPERTY INCLUDE_DIRECTORIES ...)补全头文件路径 - 遇到大小写冲突，优先换用 release tarball（
URL+URL_HASH），绕过 Git checkout
最麻烦的其实是隐式依赖传递：某个库内部 find_package 了另一个没被你声明的组件，FetchContent 不会自动递归拉取——这时候就得翻它 CMakeLists.txt，手动补全声明。
