中大型C++项目在Sublime Text中手写JSON构建系统必然失败，因其无法支持CMake的configure/build分离模型、Kit元数据联动、CMAKE_PREFIX_PATH注入及compile_commands.json生成等核心机制。
中大型 C++ 项目在 Sublime Text 里硬写 JSON 构建系统，configure 卡死、build 报 Unknown option --config、target 列表为空——不是配置漏了字段，而是这条路本身就不该走。
为什么手写 .sublime-build 在中大型项目里必然失败
Sublime 的原生构建系统是单线程、无状态、无缓存的命令执行器。它不理解 CMake 的 configure/build 分离模型，更无法维护 Kit、cache、generator、target 依赖图。一旦项目含 Qt 模块、Boost 查找逻辑、多 target（lib/app/test）、自定义 install 规则或 Ninja/MSVC 混合 generator，手写 cmd 数组就只剩三种结果：
-
cmake -S . -B build成功，但后续cmake --build build --config Release报错：旧版 CMake（如 3.10）根本不支持--config，得降级用mingw32-make -C build或msbuild build\myapp.vcxproj - Windows 下路径写成
./build/myapp，CMD 直接报“找不到文件”，必须写成build\myapp.exe - Qt 项目里
find_package(Qt6 REQUIRED)找不到模块，因为 CMake Tools 插件没注入CMAKE_PREFIX_PATH，而手写构建系统连这个变量都传不进去
CMake Tools 插件必须打开文件夹，不是打开单个 CMakeLists.txt
插件靠扫描项目根目录下的 CMakeLists.txt + 缓存 + Kit 元数据联动工作。如果只是双击打开一个 CMakeLists.txt 文件，Ctrl+Shift+P 里搜不到 CMake: Configure，面板里也看不到 target 列表——插件压根没激活。
- 正确操作是
File → Open Folder…，选整个项目根目录（含CMakeLists.txt和src/、include/等子目录） - 首次运行
CMake: Configure时提示选择 Kit，Kit 名称必须和你本地安装的编译器/Qt 版本严格匹配，例如Qt 6.7.2 (MinGW 11 64-bit)；若显示Visual Studio 17 2022却没装对应 MSVC 工具集，configure 必然卡住 - configure 后生成的
build/目录不能手动删，否则插件状态错乱；要重来就用CMake: Delete Cache and Re-configure
让 clangd 补全真正可用，光有 CMake Tools 不够
CMake Tools 负责 configure/build，但不自动生成 compile_commands.json。而 clangd 补全质量完全取决于这份文件是否准确、是否覆盖所有源码路径。
立即学习“C++免费学习笔记（深入）”；
- 必须在 configure 阶段显式启用导出：运行
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON - 或者在
CMakeLists.txt里加set(CMAKE_EXPORT_COMPILE_COMMANDS ON)，确保每次 configure 都刷新 - 确认
build/compile_commands.json存在且非空；若为空，检查是否漏了add_executable()或add_library()，或源文件路径写错（比如用了相对路径但没设CMAKE_SOURCE_DIR）
最常被忽略的一点：CMake Tools 插件对 CMAKE_PREFIX_PATH 的注入只发生在 configure 阶段，且只读取当前 Kit 关联的 Qt 安装路径。如果你改了 Qt 安装位置却没重选 Kit，或者在 CMakeLists.txt 里用 find_package(Qt6 REQUIRED) 却没配 PATHS，configure 就会静默跳过 Qt 模块——build 成功，但链接时报 undefined reference，debug 时才发现头文件根本没被 clangd 索引到。
