优先使用 find_package 或 FetchContent，避免手动配置路径；find_package 仅定位已安装库，不自动安装，需确认库是否提供 Config.cmake 文件；FetchContent 需锁定 tag 并注意调用顺序；动态库需处理运行时路径，C++标准版本必须统一。

直接说结论：优先用 find_package 或 FetchContent，别手动写 include_directories 和 link_directories —— 容易漏路径、难维护、跨平台出问题。

find_package 找不到库？先确认它是否真支持 Config 模式

很多新手以为 find_package(fmt) 能自动下载安装，其实它只负责“找”，不负责“装”。能否找到，取决于你系统里有没有 fmtConfig.cmake 或 fmt-config.cmake 文件。

• 支持 Config 模式的库（如 fmt、Eigen、OpenCV 4.5+）：推荐加 CONFIG 限定，避免误用 Module 模式：find_package(fmt CONFIG REQUIRED)
• 不带 Config 文件的库（如老版本 Boost）：CMake 会退回到 FindBoost.cmake 模块，这时得手动指定 COMPONENTS，且变量名可能不统一（Boost_INCLUDE_DIRS vs Boost_INCLUDE_DIR）
• 找不到？检查 CMAKE_PREFIX_PATH 是否包含库安装路径，比如 vcpkg 安装后要加：cmake -DCMAKE_PREFIX_PATH=/path/to/vcpkg/installed/x64-linux ..
• 常见错误：Could NOT find fmt (missing: fmt_DIR) → 不是库没装，而是 CMake 没在默认路径下发现它的配置文件

FetchContent 下载失败或 CI 构建漂移？锁定 tag，别用 branch

FetchContent 是现代项目首选，但它依赖网络和 Git 稳定性。CI 上构建失败，八成是这里出了问题。

C++ Code Review Master

组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。

下载

• 必须用稳定 tag，不是 main 或 master：GIT_TAG 10.2.1，否则某天远程分支更新了，你的构建就悄无声息地变了
• FetchContent_MakeAvailable(fmt) 必须放在 add_executable / add_library 之后、target_link_libraries 之前，否则 target 接口不可见
• 纯头文件库（如 nlohmann_json）不需要编译，但依然要调用 FetchContent_MakeAvailable 才能导出 nlohmann_json::nlohmann_json target
• 网络受限环境？提前用 FetchContent_Populate + 缓存目录，或改用 add_subdirectory 预置源码

add_subdirectory 为什么链接时报 undefined reference？作用域没设对

把第三方源码放进 third_party/ 直接 add_subdirectory 看似简单，但链接失败很常见——根本原因不是找不到符号，而是接口没暴露给下游 target。

• target_link_libraries(app PRIVATE fmt::fmt) 中的 PRIVATE 表示：app 能用 fmt，但 app 的调用者不能继承这个依赖。如果 app 是个库，而上层可执行文件又用到了 fmt 的类型（比如 fmt::format 返回值），就得改成 PUBLIC 或 INTERFACE
• 第三方库的 CMakeLists.txt 如果没正确设置 target_include_directories(... INTERFACE ...)，你的 target 就看不到头文件，报 fatal error: fmt/core.h: No such file
• 多个 target 同时 add_subdirectory 同一个库？CMake 会报错：add_subdirectory cannot be invoked multiple times for the same source directory → 改用 FetchContent 或全局一次 add_subdirectory 后导出 target

静态库链接后运行时报 “xxx not found”？动态库路径没处理

用 target_link_libraries(myapp /path/to/libabc.a) 是静态链接，没问题；但若链接的是 .so 或 .dll，编译通过不等于运行成功。

• Linux 下运行时报 libabc.so: cannot open shared object file：不是链接错了，而是运行时找不到动态库。要么把路径加进 LD_LIBRARY_PATH，要么在 CMake 里用 set_target_properties(myapp PROPERTIES INSTALL_RPATH "$ORIGIN/../lib")
• macOS 上类似问题对应 DYLD_LIBRARY_PATH 或 @rpath，需额外设 INSTALL_RPATH_USE_LINK_PATH
• Windows 不报错但崩溃？检查是否混用了不同 CRT（/MT vs /MD），第三方库和主项目必须一致

最常被忽略的一点：C++ 标准版本不一致。比如 fmt 用 C++17 编译，而你的项目是 set(CMAKE_CXX_STANDARD 20)，某些模板实例化可能失败。统一标准比调路径更优先。