cmake tools插件必须打开整个文件夹而非单个cmakelists.txt文件，依赖完整项目结构识别子目录、缓存和kit；windows路径含空格需手动修改cmake-kits.json，macos需确认qt6路径含lib/cmake/qt6；kit须精确匹配编译器与qt版本；configure失败应查首条错误；必须启用cmake_export_compile_commands=on以支持clangd；推荐用cmake-presets.json统一管理多平台构建；build目录不可手动删除，须用“delete cache and re-configure”。
Sublime Text里CMake Tools插件必须打开整个文件夹
插件根本不会启动，如果你只是双击打开一个CMakeLists.txt文件。它依赖项目根目录下的完整结构（包括src/、include/、tests/等子目录）来识别add_subdirectory()、缓存状态和Kit元数据。打开方式只能是File → Open Folder…，选中含CMakeLists.txt的最外层目录。
常见错误现象：按Ctrl+Shift+P搜不到CMake: Configure，状态栏不显示Kit图标，target列表为空——基本就是这个原因。
- Windows路径含空格（如
C:Program FilesQt.7.2mingw_64）时，CMake Tools Kit编辑器无法直接输入引号，得手动改cmake-kits.json，在env字段里写："CMAKE_PREFIX_PATH": "C:\Program Files\Qt\6.7.2\mingw_64" - macOS上Homebrew装的Qt默认在
/opt/homebrew/opt/qt，要确认该路径下存在lib/cmake/Qt6，否则find_package(Qt6 REQUIRED)会静默失败
Kit选择必须和本地安装严格匹配
不是“GCC”或“MSVC”这种泛称就行，而是要精确到编译器版本+Qt绑定版本。比如你装的是Qt 6.7.2 (MinGW 11 64-bit)，Kit列表里就得选这一项；若只装了Visual Studio 17 2022但没装对应MSVC工具集，选了也会卡在“Configuring…”不动。
configure失败时，别只看最后一行Configuring incomplete，翻输出面板最上面找第一处CMake Error或WARNING:：
-
Unable to find qmake→ 检查qmake是否在PATH，或Qt6_DIR是否指向lib/cmake/Qt6（不是bin/） -
CMAKE_CXX_COMPILER is not a full path→ Kit里选的编译器路径和实际g++/cl.exe位置不一致 -
Could not find a package configuration file for "fmt"→ 外部库装在非标准路径，需在Kit的CMAKE_PREFIX_PATH里手动加路径
必须显式启用CMAKE_EXPORT_COMPILE_COMMANDS=ON
CMake Tools自己不会生成compile_commands.json，而clangd补全质量完全取决于它。不加这句，就算configure成功、build能跑，补全也大概率找不到头文件、跳转失效、宏定义不识别。
正确做法是在首次CMake: Configure时，在命令行参数里加上：-DCMAKE_EXPORT_COMPILE_COMMANDS=ON。也可以在cmake-presets.json里固化：
{
"configurePresets": [{
"name": "linux-gcc-release",
"displayName": "Linux GCC Release",
"generator": "Ninja",
"binaryDir": "${sourceDir}/build",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Release",
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
}
}]
}
注意：CMAKE_EXPORT_COMPILE_COMMANDS是布尔开关，值必须是ON或OFF，不能写True或1。
多平台构建别硬切cmd数组，用CMake Presets统一管理
手写.sublime-build文件里塞"windows": {...}和"linux": {...}，很快就会失控——尤其当你要切Ninja vs Unix Makefiles、MSVC vs MinGW、Debug/Release配置时。CMake原生的presets机制才是跨平台稳定解。
把平台差异收进cmake-presets.json，CMake Tools会自动读取并提供下拉菜单选择：
- Windows + MSVC：用
"generator": "Visual Studio 17 2022"，"architecture": "x64" - Linux/macOS + Ninja：用
"generator": "Ninja"，配合ccache加速（需提前在系统级配置） - Qt项目务必在每个preset里加
"cacheVariables": {"CMAKE_PREFIX_PATH": "..."}，路径按平台实际调整
真正容易被忽略的是：build/目录一旦生成，就别手动删。删了会导致CMake Tools内部状态错乱，后续configure可能报Cache is invalid。要重来，必须用CMake: Delete Cache and Re-configure，而不是rm -rf build。
