CMakeLists.txt必须按正确顺序编写：先cmake_minimum_required和project，再add_executable，最后target_link_libraries；目标未定义、名称错误、作用域越界或缓存残留均会导致链接失败。
不是“怎么写”，而是“怎么写对”——CMakeLists.txt 写错一个 target_link_libraries 顺序，链接就失败；少一个 find_package，add_executable 就报找不到头文件；路径用相对还是绝对，include_directories 和 target_include_directories 混用，编译结果可能当场不可复现。
从最简可构建的 CMakeLists.txt 开始
别一上来就抄模板。先让一个 main.cpp 能编译通过，再加功能：
cmake_minimum_required(VERSION 3.10) project(hello) <p>add_executable(hello main.cpp)
这是唯一必须的最小结构。注意三点：
-
cmake_minimum_required版本不能低于你本地 CMake —— 运行cmake --version看实际版本，写低了会报CMake Error: The required version of CMake is not available -
project()必须在add_executable前，否则PROJECT_NAME等变量为空，后续逻辑可能崩 -
add_executable的源文件路径是相对于CMakeLists.txt所在目录的，写src/main.cpp就得确保文件真在那，别靠 IDE 自动补全瞎猜
添加头文件和第三方库时，优先用 target_* 接口
老教程里满屏的 include_directories 和 link_directories 是反模式：它们作用于全局，容易污染其他 target，且无法控制依赖传递性。
正确做法是绑定到具体 target：
add_executable(app main.cpp)
target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
target_link_libraries(app PRIVATE fmt::fmt)关键区别：
-
PRIVATE表示只影响app自身编译，不暴露给依赖它的其他 target；PUBLIC才会把 include 路径/链接项透出 -
fmt::fmt是现代 CMake 的 imported target 写法，比find_package(fmt REQUIRED)+target_link_libraries(app fmt)更安全——前者自动带 include、link、compile options，后者漏掉fmt_INCLUDE_DIRS就编译不过 - 不要写
target_include_directories(app PRIVATE ./include)——.是相对当前CMakeLists.txt的路径，但 CMake 不保证执行时工作目录就是这里；用${CMAKE_CURRENT_SOURCE_DIR}才稳
跨平台路径和条件编译别硬编码
Windows 下路径分隔符是 \，Linux/macOS 是 /，但 CMake 提供了抽象接口：
- 拼接路径用
join_path（CMake 3.20+）：set(HEADER_PATH $<join:>)</join:>或更稳妥的file(TO_CMAKE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/include" HEADER_PATH) - 判断系统用
WIN32/APPLE/UNIX变量：if(WIN32) target_compile_definitions(app PRIVATE _CRT_SECURE_NO_WARNINGS) endif() - 别写
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")——CMAKE_SYSTEM_NAME在交叉编译时可能不准，UNIX更可靠
常见坑：add_definitions(-DDEBUG) 全局生效，所有 target 都被加上；应改用 target_compile_definitions(app PRIVATE DEBUG)，否则静态库里的 release 代码也可能被误打上 debug 宏。
生成构建目录前，先检查缓存是否残留旧配置
CMake 缓存顽固，CMakeCache.txt 和 CMakeFiles/ 目录不清理，改了 find_package 版本或路径都可能继续用旧值。
实操建议：
- 永远在独立目录中运行 CMake：
mkdir build && cd build && cmake ..，别在源码根目录cmake . - 改完 CMakeLists.txt 后，删掉整个
build/目录重来，比cmake --build . --clean-first更彻底 - 遇到
Could NOT find XXX (missing: XXX_LIBRARIES)却确认已安装，先运行cmake -DXXX_ROOT=/path/to/xxx ..显式指定路径，再看是不是缓存记住了错误路径
复杂点在于：CMake 的“隐式行为”太多——比如 find_package 默认走 CMAKE_PREFIX_PATH，而这个变量可能被环境变量、命令行、甚至别的 find_package 修改过。调试时直接看 CMakeCache.txt 里对应变量的值，比猜更快。
