fetchcontent 在 cmake 配置阶段完成下载与构建，非构建时；需成对使用 declare 与 makeavailable；必须在 project() 后、add_executable() 前 include(fetchcontent)；重复 declare 报错；默认复用缓存；git 不可达是常见失败原因；头文件库仍需正确导出目标名。
FetchContent 不是在构建时下载，而是在 cmake 配置阶段（configure phase）就完成下载、解压、配置和构建——它不依赖 make 或 ninja 启动后才执行。这点常被误解，直接导致 CI 失败或本地构建行为不一致。
FetchContent_Declare 和 FetchContent_MakeAvailable 必须成对出现
FetchContent_Declare 只是注册一个依赖声明，不触发任何下载；真正拉取并构建的是 FetchContent_MakeAvailable。漏掉后者，CMake 会静默跳过该依赖，链接时报 target not found 错误。
- 必须在
project()之后、add_executable()之前调用include(FetchContent) - 同一个依赖名（如
fmt）不能重复Declare，否则 CMake 报错FetchContent_Declare called twice for 'fmt' - 若依赖已存在（比如之前成功运行过），
FetchContent_MakeAvailable默认复用缓存，不会重下——除非加UPDATE_DISCONNECTED OFF或手动删_deps/目录
Git 仓库下载失败：不是网络问题，而是 git 命令不可达
错误信息如 Failed to run 'git' command，本质是 CMake 在 PATH 中找不到 git 可执行文件。Windows 上尤其常见：VS 开发者命令行默认不带 Git，MSYS2 或 Git for Windows 安装时没勾选 “Add Git to PATH”。
CMake 4.3.2 Windows x86_64 历史版本安装包，适合旧项目兼容、构建环境回退、CMakeLists.txt 迁移验证、Visual Studio/Ninja/Makefile 生成器测试和 C/C++ 项目维护。
- CI 环境（GitHub Actions、GitLab CI）必须显式安装 Git：
apt-get install git（Ubuntu）、choco install git（Windows） - 可在 CMakeLists.txt 开头加
find_package(Git REQUIRED)提前检测，并用${GIT_EXECUTABLE}打印路径验证 - 避免用
URL+URL_HASH替代 Git 方式——虽然能绕过 Git 依赖，但失去分支/Tag 灵活性，且无法做 shallow clone 或 submodule 初始化
头文件库（如 nlohmann_json）不用编译，但仍有陷阱
纯头文件库看似简单，但 FetchContent_MakeAvailable 仍会执行 configure 步骤。若对方 CMakeLists.txt 中有 add_library(... INTERFACE)，你才能用 target_link_libraries(myapp PRIVATE nlohmann_json::nlohmann_json)；否则可能只导出 INTERFACE_INCLUDE_DIRECTORIES，需手动 target_include_directories。
- 确认目标名：查看依赖项目的
CMakeLists.txt，找add_library(... EXPORT)或install(EXPORT)语句，目标名未必等于FetchContent_Declare的第一个参数 - 强制设为头文件库模式：对无 CMake 支持的纯头库，可用
set(nlohmann_json_SOURCE_DIR ${CMAKE_CURRENT_BINARY_DIR}/_deps/nlohmann_json-src)+add_library(nlohmann_json INTERFACE)+target_include_directories(nlohmann_json INTERFACE $<include>)</include> - 别在
FetchContent_Declare后立刻set(... CACHE ... FORCE)——部分库（如 yaml-cpp）要求选项在MakeAvailable前设置，否则被忽略
最易被忽略的一点：FetchContent 下载的依赖默认构建在 ${CMAKE_BINARY_DIR}/_deps/，这个路径既不在 git status 中，也不受 IDE 自动索引覆盖。如果你改了依赖源码又没推到远端，下次 cmake .. 会静默复用旧缓存——调试时以为改了代码，实际跑的根本不是你的修改。
