CLion创建大型C++项目须采用分层CMake结构：根目录CMakeLists.txt定义项目并调用add_subdirectory引入src/、tests/等子目录，各子目录用add_library定义模块，通过target_include_directories显式声明头文件范围，add_executable目标名须全局唯一，依赖须用find_package或FetchContent声明，工具链切换后需手动Reload CMake project。
CLion 创建大型 C++ 项目时，CMakeLists.txt 不能只写一层
大型项目几乎必然需要多级目录结构（如 src/、include/、libs/、tests/），而 CLion 默认新建的“C++ Executable”项目只生成单层 CMakeLists.txt 和一个 main.cpp。直接往里塞几十个源文件，不拆分 CMake 配置，会导致：add_executable 列表爆炸、头文件路径混乱、编译依赖失效、IDE 索引变慢甚至卡死。
正确做法是启用「分层 CMake」：在根目录保留顶层 CMakeLists.txt 做项目定义和子目录引入，在每个逻辑模块下（如 src/core/、src/network/）各自放一个 CMakeLists.txt，用 add_library 定义静态/接口库，再由根目录统一链接。
- 根
CMakeLists.txt中必须包含add_subdirectory(src)、add_subdirectory(tests)等调用 - 子目录
CMakeLists.txt里避免写project()或重复设置CMAKE_CXX_STANDARD - 所有
target_include_directories(... PUBLIC ...)必须显式声明头文件可见范围，否则#include "xxx.h"在其他模块会报错 - CLion 默认不会自动识别新增的子
CMakeLists.txt—— 修改后需点击右下角Load CMake project或手动触发重新加载
多个可执行目标共存时，add_executable 名称不能重复且必须唯一
大型项目常含主程序、单元测试、工具脚本等多个入口。若在同一个 add_executable 调用里堆砌所有 .cpp 文件，或在不同 CMakeLists.txt 中用了相同目标名（比如都叫 app），CMake 会直接报错：CMake Error: add_executable cannot create target "app" because another target with the same name already exists。
解决的关键不是“怎么加”，而是“怎么命名+怎么隔离”：
立即学习“C++免费学习笔记（深入）”；
- 每个
add_executable的第一个参数（目标名）必须全局唯一，建议带前缀，如myapp_main、myapp_test_runner、myapp_gen_config - 不要把测试代码和主逻辑混在一个 target 里；用
enable_testing()+add_test()显式注册测试，CLion 的测试工具窗口才能识别 - 如果某个
.cpp文件只用于调试临时运行（比如debug_dump.cpp），单独建一个 target 并禁用默认构建：set_target_properties(debug_dump PROPERTIES EXCLUDE_FROM_ALL TRUE)
第三方依赖（如 OpenMPI、Boost、fmt）不能靠手动改 PATH 解决
新手常试图把 libmpi.dll 扔进项目目录，或改系统环境变量让 g++ 找到头文件——这在 CLion 里完全无效。CLion 构建流程严格走 CMake，所有依赖必须通过 CMake 声明，否则：#include <mpi.h> 红色波浪线不消失、find_package(MPI REQUIRED) 报错找不到包、链接阶段提示 undefined reference to MPI_Init。
真实可行的路径只有两条：
- 用
find_package(<Name> REQUIRED)+target_link_libraries(<target> PRIVATE <Name>::<Target>)，前提是系统已安装对应开发包（如mingw-w64-x86_64-openmpi）且 CMake 能搜到Find<Name>.cmake或<Name>Config.cmake - 用
FetchContent_Declare在 CMake 内部拉取源码并构建（适合 fmt、spdlog 这类 header-only 或自带 CMake 的库），但要注意避免重复 fetch、控制构建选项（如FMT_INSTALL OFF） - 绝对不要在
CMakeLists.txt里硬编码include_directories("C:/libs/boost")或link_directories("C:/libs/mpi/lib")—— 这会让项目失去可移植性，且 CLion 的代码补全和跳转会失效
CLion 的 CMake 工具链配置错误会导致整个项目“失联”
大型项目对编译器特性（如 C++20 modules、concepts）、标准库实现（libstdc++ vs libc++）、架构（x86_64 vs aarch64）极其敏感。如果 CLion 工具链选错，会出现诡异现象：CMake 配置成功、但 main.cpp 里 std::format 仍标红；或者构建通过，运行时报 MSVCP140.dll missing；更糟的是，CMakeLists.txt 语法高亮全灭，连 add_executable 都不识别。
检查点必须覆盖三层：
- CLion 设置 → Build, Execution, Deployment → Toolchains：确认选中的是你实际想用的工具链（如
Bundled MinGW或Visual Studio 2022），而不是灰色不可用项 - 同一页面下的
CMake profiles：确保当前激活的 profile 使用了正确的Toolchain和Build type（Debug/RelWithDebInfo），且CMake options里没误加-G "MinGW Makefiles"（CLion 默认用 Ninja，混用会失败） - 终端里手动运行
cmake --version和对应编译器（如g++ --version）验证版本是否匹配项目要求；若不一致，要么换工具链，要么在 CMake 中用set(CMAKE_CXX_STANDARD 17)显式降级
最易被忽略的是：当你切换工具链后，CLion 不会自动重载 CMake 缓存。必须手动点击 Reload CMake project，否则旧配置仍在内存里跑，一切修改都像没发生过。
