CMake Tools 是中大型 C++ 项目唯一可行路径，因其支持 Kit 切换、多配置构建、target 依赖分析、install 规则及 find_package 路径控制，而手写 .sublime-build 无法处理这些复杂需求，且错误日志不透明。
Sublime Text 本身不支持 CMake，中大型 C++ 项目必须用 CMake Tools 插件，手写 .sublime-build 文件只适用于单文件、无 Qt/Boost/多 target 的极简场景——否则 configure 卡死、build 报 Unknown option --config、target 列表为空是必然结果。
为什么 CMake Tools 是唯一可行路径
原生构建系统无法处理 Kit 切换、多配置（Debug/Release）、find_package(Qt6 REQUIRED) 路径解析、add_subdirectory() 递归扫描、install 规则或 Ninja/MSVC/MinGW generator 自动适配。你手动写 "cmd": ["cmake", "-B", "build"]，一旦项目加了 Qt 或换编译器，就得重配整个 JSON，且错误日志只显示 “command failed”，根本看不出是缺 qmake 还是 CMAKE_PREFIX_PATH 指错了。
-
CMake Tools提供状态栏实时提示 configure 进度、Kit 选择界面、target 下拉菜单和折叠日志，相当于把 CMake CLI 黑盒操作可视化 - 它依赖项目根目录下的
CMakeLists.txt+ 缓存 + Kit 元数据联动工作，不是靠拼命令实现的 - 插件不解决环境问题，只是调度器：cmake、qmake（Qt 项目）、编译器三者必须在终端能直接运行，否则 configure 必卡在 “Confi” 截断状态
Windows / macOS / Linux 共同前提
跨平台配置失败，90% 出在环境变量没对齐。GUI 启动的 Sublime 不继承 shell 的 PATH，尤其 macOS 和 Windows 常见此问题。
- Windows：MinGW-w64 安装时务必勾选 “Add to PATH”；若已装完，手动把
C:mingw64in加进系统环境变量，重启 Sublime - macOS：Homebrew 安装的 GCC 默认叫
g++-14（不是g++），运行ls /opt/homebrew/bin/g++*确认真实名称；从终端执行open -a "Sublime Text"启动，否则读不到 shell 的PATH - Linux / WSL2：确保用的是 Linux 版 Sublime（不是 Windows 版），且
which g++输出非空；WSL2 用户若用 Windows 版 Sublime，根本调不动 WSL 里的g++ - 所有平台：终端里能跑
cmake --version和g++ --version，不代表 Sublime 就能用——必须验证 Sublime 内部能否调通
CMake Tools 首次配置必踩的三个坑
按 Ctrl+Shift+P 输入 CMake: Configure 失败？别急着重试，先查这三点：
立即学习“C++免费学习笔记（深入）”；
- 必须用
File → Open Folder…打开整个项目根目录（含CMakeLists.txt和源码子目录），不能只双击打开单个CMakeLists.txt文件——否则插件压根不会激活 - Kit 名称必须和本地安装严格匹配，例如
Qt 6.7.2 (MinGW 11 64-bit)或Visual Studio 17 2022；若选了Visual Studio 17 2022却没装对应 MSVC 工具集，configure 必然卡住 - Qt 项目需在
CMakeLists.txt里显式设置路径：set(CMAKE_PREFIX_PATH "C:/Qt/6.7.2/mingw_64")（Windows）或set(CMAKE_PREFIX_PATH "/opt/homebrew/opt/qt")（macOS），否则find_package(Qt6 REQUIRED)找不到模块
configure 成功后仍看不到补全？clangd 没连上 compile_commands.json
CMake Tools 负责 configure 和 build，但智能补全靠 clangd，而它需要准确的 compile_commands.json ——这个文件不会自动生成，必须由 CMake 显式导出。
- 在
CMakeLists.txt顶部加一行：set(CMAKE_EXPORT_COMPILE_COMMANDS ON) - 或在 configure 命令里加选项：
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON - 生成后，确保
clangd插件指向该文件：在clangd.sublime-settings中设"compilationDatabasePath": "${project_path}/build" - Windows 下路径含空格（如
C:Program FilesQt.7.2msvc2019_64）必须用双引号包裹，但CMake Tools的 Kit 编辑器不支持直接输引号——得改cmake-kits.json，在对应 Kit 的env字段里写："CMAKE_PREFIX_PATH": "C:\Program Files\Qt\6.7.2\msvc2019_64"
最易被忽略的是：configure 后生成的 build/ 目录不能手动删，否则插件状态错乱；要重来就用 CMake: Delete Cache and Re-configure。跨平台项目里，generator 值必须匹配系统——Linux/macOS 用 Unix Makefiles，Windows 若装了 Visual Studio 应改为 Visual Studio 17 2022，否则 configure 直接失败。
