CMake不是编译器也不是Make替代品，它只负责读CMakeLists.txt并生成平台专属构建文件；新手常见错误是混淆配置与构建阶段、源码与构建目录混用，正确做法是显式使用cmake -S . -B build。
直接说结论：CMake 不是编译器，也不是 Make 的替代品，它只干一件事——读 CMakeLists.txt，生成适合当前平台的构建文件（比如 Makefile 或 .sln）。新手卡住，90% 是因为没分清「配置」和「构建」两个阶段，或者把构建产物混在源码目录里。
cmake 命令必须带 -B 和 -S 参数才可靠
老教程里常见的 cmake . 或 cmake .. 看似简单，但隐含路径歧义，尤其在嵌套子项目或 CI 环境中极易出错。现代 CMake（3.13+）明确推荐显式指定源码和构建目录：
-
cmake -S . -B build：源码在当前目录，构建输出到build/子目录（最安全、最清晰） -
cmake -S /path/to/src -B /path/to/build：绝对路径，彻底规避相对路径误判 - 千万别用
cmake .在源码根目录执行——它会把CMakeCache.txt、Makefile全塞进源码树，污染 Git、干扰 IDE、后续 clean 极难彻底 - 如果报错
Cannot open file CMakeCache.txt或Source directory does not appear to contain CMakeLists.txt，八成是当前路径错了，先pwd确认再执行
add_executable() 里的源文件路径必须是相对路径，且相对于当前 CMakeLists.txt
这是新手最常栽跟头的地方。CMake 不会自动递归找源码，也不会按环境变量或全局路径解析。比如你有如下结构：
project/
├── CMakeLists.txt
├── src/
│ └── main.cpp
└── include/
└── utils.hpp
那么 CMakeLists.txt 中必须写：
add_executable(myapp src/main.cpp)
而不是 add_executable(myapp ./src/main.cpp) 或 add_executable(myapp /home/user/project/src/main.cpp)。原因：
-
./开头的路径在 CMake 中会被当作绝对路径处理，导致找不到文件 - 绝对路径硬编码彻底破坏跨平台性和可移植性
- 如果用了
add_subdirectory(src)，那src/CMakeLists.txt里的add_executable()就只能写main.cpp（因为当前目录已切换到src/）
CMAKE_CXX_STANDARD 必须配合 CMAKE_CXX_STANDARD_REQUIRED 使用
只设 set(CMAKE_CXX_STANDARD 17) 是不够的。CMake 默认允许降级使用更低标准（比如编译器不支持 C++17 时悄悄退到 C++14），这会导致行为不一致甚至静默编译通过但运行异常。正确写法是：
set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)
这样一旦编译器不支持 C++17，cmake 配置阶段就直接报错，不会等到 make 时才发现 std::optional 找不到。另外注意：
-
CMAKE_CXX_STANDARD只影响后续定义的 target，对之前已声明的add_executable()无效——所以它得放在add_executable()之前 - 若项目同时含 C 和 C++ 文件，还得加
set(CMAKE_C_STANDARD 11)和set(CMAKE_C_STANDARD_REQUIRED ON) - 别用
set(CMAKE_CXX_FLAGS "-std=c++17")替代——这是绕过 CMake 标准机制的野路子，会破坏 target 属性继承和跨编译器兼容性
find_package() 找不到包？先看是否漏了 REQUIRED 或 QUIET
find_package(OpenCV) 没报错但后续 target_link_libraries(myapp ${OpenCV_LIBS}) 失败，大概率是包根本没找到，而默认行为是静默跳过。关键点：
- 加
REQUIRED：如find_package(OpenCV REQUIRED)，找不到立刻中断并提示缺失，避免后继链接失败时错误信息晦涩难懂 - 加
QUIET：仅用于探测性检查（比如判断是否可用某可选功能），但必须自己手动检查OpenCV_FOUND变量再分支处理 - 别依赖
OpenCV_LIBS这类旧式变量——现代写法是target_link_libraries(myapp PRIVATE OpenCV::opencv_core)，靠 imported target 保证接口和依赖传递正确 - 如果系统装了 OpenCV 但
find_package还是失败，试试find_package(OpenCV REQUIRED PATHS /usr/local/share/opencv4)显式指定 hint 路径
最易被忽略的其实是构建目录的生命周期管理：每次改完 CMakeLists.txt，不要只 make，而要进 build/ 目录重新跑一遍 cmake -S .. -B .——否则旧缓存可能让新配置不生效，尤其是增删 target 或改 set() 变量时。CMake 的「惰性重配置」机制不是 bug，是设计，但得你主动触发。
