fetchcontent_declare 不支持 git+ssh 协议，因其默认使用 cmake -e download（不支持 ssh 认证），需改用 https+pat 或确保 git 可用并配置 ssh；头文件缺失须通过 target_link_libraries 依赖目标并正确设置 interface include；提速需启用 git_shallow on、锁定版本、合理配置 fetchcontent_base_dir；长期维护推荐 find_package(config) 替代。
FetchContent_Declare 为什么不能直接用 git+ssh 协议
因为 CMake 3.14+ 的 FetchContent_Declare 默认调用的是 CMake 内置的下载器（cmake -E download），它不支持 git+ssh:// 这类需要 SSH 密钥认证的协议。如果你写成 GIT_REPOSITORY "git+ssh://git@github.com:org/repo.git"，会报错：Failed to fetch content 或 Unknown protocol 'git+ssh'。
解决办法是显式指定使用 Git 命令行工具，并确保环境里有可用的 git（且已配置好 SSH key）：
FetchContent_Declare( mylib GIT_REPOSITORY https://github.com/org/repo.git GIT_TAG v1.2.0 GIT_SHALLOW ON ) # ✅ 关键：启用 Git 工具（CMake 自动检测，但可强制） set(FETCHCONTENT_FULLY_DISCONNECTED OFF) FetchContent_MakeAvailable(mylib)
如果必须用 SSH 地址（比如私有仓库），改用 https:// + personal access token（PAT）更稳妥，例如：https://<token>@github.com/org/private-repo.git</token>；否则需确认构建机上 git 可执行且 ssh-agent 已加载密钥。
FetchContent_MakeAvailable 后头文件找不到？检查 target_include_directories
FetchContent_MakeAvailable 只负责拉取、配置并生成 target，但不会自动把头文件路径暴露给你的主项目。常见现象是编译时报错：fatal error: xxx.h: No such file or directory，即使 mylib 的 CMakeLists.txt 正确设置了 target_include_directories。
原因在于：CMake 的 include 目录传播是“按需继承”的，你得显式链接 target 并依赖其接口属性：
- 确保外部库 target（如
mylib）在自己的CMakeLists.txt中声明了target_include_directories(mylib INTERFACE $<include> $<build_interface:>)</build_interface:></include> - 在你的主
add_executable或add_library后，加上target_link_libraries(your_target PRIVATE mylib) - 不要手动加
include_directories(...)—— 这会绕过接口传播，且破坏可移植性
验证方式：运行 cmake --build . --verbose，看编译命令里是否含 -I/path/to/mylib/include。
如何避免重复 clone 和反复 configure 外部库
默认情况下，每次 cmake .. 都会重新检查 FetchContent 状态，对大型 Git 仓库（尤其没设 GIT_SHALLOW ON）很慢。这不是 bug，而是设计行为 —— CMake 为保证确定性，默认不缓存。
提速的关键配置：
- 始终启用
GIT_SHALLOW ON（跳过完整历史，快 5–10 倍） - 用
GIT_TAG或GIT_COMMIT锁定版本，避免main分支漂移导致 rebuild - 设置
FETCHCONTENT_QUIET ON减少日志干扰（非性能项，但实操中常被忽略） - 若用 CI/CD，可提前在镜像中预 populate
FETCHCONTENT_BASE_DIR（默认是${CMAKE_BINARY_DIR}/_deps），避免每次从零拉
注意：FETCHCONTENT_BASE_DIR 一旦设定，所有 FetchContent_Declare 共享该目录 —— 别把它设成临时路径或 NFS 挂载点，否则并发构建可能冲突。
CMake 3.20 之后的替代方案：find_package + CONFIG 模式更适合长期维护
当外部库本身提供 FooConfig.cmake（比如 modern-cpp-json、spdlog、fmt），优先走 find_package(Foo CONFIG REQUIRED)，而不是 FetchContent。前者能复用系统级安装、支持 version range（find_package(Foo 1.2...2.0 REQUIRED)），且不污染构建树。
FetchContent 的本质是“嵌入式依赖管理”，适合以下场景：
- 库尚未发布正式 CMake config 文件（比如 fork 后未 upstream 的分支）
- 需要 patch 源码（配合
PATCH_COMMAND） - 项目必须离线构建，且允许把依赖源码打进代码仓（
FetchContent_Populate+add_subdirectory）
混用二者时注意：如果同时用了 find_package 和 FetchContent_Declare 同名库，CMake 会报 Cannot find package "X" because it is already defined as an imported target —— 这是保护机制，不是错误，删掉其中一个即可。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
