必须使用 out-of-source 构建，即在独立 build 目录运行 cmake ..，避免中间文件污染源码；最小 cmakelists.txt 需三行：cmake_minimum_required(version 3.10)、project(hello)、add_executable(hello hello.cpp)。
直接在项目根目录写好 CMakeLists.txt，然后进 build 子目录运行 cmake .. —— 这就是真正可落地的第一步，不是“新建文件夹”或“安装软件”那种准备动作。
为什么必须用 out-of-source 构建？
因为 cmake 会在构建目录里生成大量中间文件（CMakeCache.txt、Makefile、CMakeFiles/ 等），混在源码里会污染 Git、干扰 IDE、导致重复配置失败。几乎所有现代 CMake 教程默认都走这个路径。
- 错误做法：
cmake .（当前目录既是源码又是构建目录） - 正确做法：
mkdir build && cd build && cmake .. - Windows 上用 PowerShell 或 CMD 都行，但别用资源管理器双击运行；Linux/macOS 别漏掉
cd build这一步
CMakeLists.txt 最小可用三行怎么写？
三行是底线，少一行都会报错。注意大小写不敏感，但空格和括号必须严格匹配：
cmake_minimum_required(VERSION 3.10) project(hello) add_executable(hello hello.cpp)
-
cmake_minimum_required版本太低（如2.6）在新系统上可能触发警告甚至失败；3.10是目前安全下限，兼顾旧环境和现代特性 -
project名称不用和可执行文件名一致，但建议保持简单、无空格、无特殊字符 -
add_executable第二个参数是源文件路径，相对CMakeLists.txt所在位置；如果hello.cpp在src/下，就得写src/hello.cpp
运行 cmake .. 后没反应或报错，先查这三处
常见卡点不在语法，而在环境链路断了：
- 终端没找到编译器：运行
gcc --version或cl（Windows）确认能调通；CMake 不会自动装编译器，只负责找 -
CMakeLists.txt编码是 UTF-8 with BOM？Windows 记事本默认存的就是带 BOM 的，会导致Parse error；用 VS Code、Notepad++ 或iconv转纯 UTF-8 - 路径含中文或空格？CMake 对这类路径支持不稳定，尤其 MinGW 和某些旧版 Visual Studio 工具链，临时改英文路径最省事
真正容易被忽略的是：CMake 配置阶段（cmake ..）成功 ≠ 编译成功。它只保证生成了 Makefile 或工程文件；后续 make 或 cmake --build . 才真正调用编译器——这两步失败原因完全不同，别混在一起排查。
