先跑通最小可运行构建流程，再按需扩展；90%卡点源于编译器未识别或路径错误，需确保环境变量、工具链匹配及源文件路径相对cmakelists.txt正确。
直接上手做 CMake 实战项目，核心就一条：别从空目录开始写 CMakeLists.txt，先让一个最小可运行的构建流程跑通，再按需加功能。所有“卡住”的问题，90% 出现在配置阶段没理清依赖路径或编译器识别失败。
cmake .. 报错找不到编译器或 Qt6
这是最常发生的阻塞点，尤其在 Windows + MSVC 或 macOS + Xcode 场景下。CMake 不会自动猜你用哪个编译器，它只认环境变量和命令行显式指定。
- Windows 上用 MSVC：必须在 “x64 Native Tools Command Prompt for VS 2022” 里执行
cmake ..，而不是普通 PowerShell 或 CMD —— 否则cl.exe不在 PATH 里，CMake 就报Could not find compiler set in environment variable CC - macOS 上用 Clang：确保已运行
xcode-select --install，且没手动删过/Library/Developer/CommandLineTools；否则 CMake 找不到clang++，报错类似No CMAKE_CXX_COMPILER could be found - Qt6 项目报
find_package(Qt6 REQUIRED COMPONENTS Core Widgets)失败：不是 Qt 没装，而是 CMake 找不到Qt6Config.cmake。检查 Qt 安装时是否勾选了对应工具链（如 “MSVC 2022 64-bit”），然后在cmake命令中加-DCMAKE_PREFIX_PATH="C:/Qt/6.7.2/msvc2022_64"（Windows）或-DCMAKE_PREFIX_PATH="/Users/xxx/Qt/6.7.2/macos"（macOS）
add_executable() 里源文件路径写错
add_executable() 的第二个参数是源文件列表，但 CMake 默认只认相对于 CMakeLists.txt 所在目录的路径。很多人把 src/main.cpp 写成 ./src/main.cpp 或 ../src/main.cpp，结果构建时提示 “file not found”，其实只是路径解析错了。
- 正确写法是：
add_executable(myapp src/main.cpp src/utils.cpp)，前提是CMakeLists.txt在项目根目录，而src/是其子目录 - 如果源文件分散在多层目录（比如
src/core/和src/gui/），别硬拼路径，改用file(GLOB_RECURSE SOURCES "src/**/*.cpp")，但注意：GLOB 不会自动感知新增文件，需手动 re-runcmake或改用target_sources()显式管理 - 头文件路径不参与
add_executable()，但影响编译——记得用target_include_directories(myapp PRIVATE include)告诉编译器去哪找#include "xxx.h"
跨平台构建时 Windows 和 Linux 行为不一致
同一个 CMakeLists.txt 在 Windows 上能编译，在 Linux 上报错，往往不是语法问题，而是路径分隔符、大小写敏感性或默认链接行为差异导致的。
- 路径拼接一律用
${CMAKE_SOURCE_DIR}/assets/config.json，别用"C:\assets\config.json"或"C:/assets/config.json"—— CMake 内部会自动转义 - Linux 文件系统区分大小写，
#include "MyHeader.h"却实际只有myheader.h，GCC 直接报错；Windows 下 MSVC 可能容忍，造成误判 - Linux 默认不链接
stdc++或pthread，而 Windows MSVC 自动带；若代码用了std::thread，必须显式加target_link_libraries(myapp PRIVATE Threads::Threads)
真正难的不是语法，而是每次 cmake .. 后，要看懂 CMakeCache.txt 里那些 XXX_DIR 和 XXX_LIBRARIES 的实际值 —— 它们才是构建能否成功的事实依据，而不是你“以为”装了什么库。
