CMake Tools 扩展未正确配置、构建或调试项目，需依次验证扩展启用、CMakeLists.txt 有效性、手动选择 Kit、设置构建类型与目录、重置缓存；本文以 macOS Sequoia 环境为例。
如果您在 Visual Studio Code 中使用 CMake Tools 扩展管理 CMake 项目，但无法正确配置、构建或调试项目，则可能是由于扩展未正确识别 CMakeLists.txt、工具链未设置或构建目录未初始化所致。以下是解决此问题的步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、验证 CMake Tools 扩展安装与启用
CMake Tools 扩展是 VSCode 中实现 CMake 项目集成的核心组件，必须确保其已安装且处于启用状态，否则所有后续功能（如配置、构建、调试）均不可用。
1、点击左侧活动栏的扩展图标（方块拼图形状）。
2、在搜索框中输入 CMake Tools。
3、确认官方扩展由 Microsoft 发布，版本号显示为当前最新稳定版。
4、若右侧显示“禁用”按钮，则点击启用；若未安装，则点击“安装”并等待完成。
二、检查工作区根目录下 CMakeLists.txt 的存在与语法有效性
CMake Tools 仅在打开的文件夹根目录（或其子目录中通过 cmake.configureSettings 指定路径）包含有效的 CMakeLists.txt 时，才会激活配置流程。文件缺失、路径错误或语法错误将导致工具无法解析项目结构。
1、在 VSCode 文件资源管理器中确认当前打开的文件夹内存在名为 CMakeLists.txt 的文件。
2、右键该文件 → “在终端中打开”，执行命令 cmake --syntax-check CMakeLists.txt 验证基础语法。
3、检查文件首行是否包含 cmake_minimum_required(VERSION ...)，且版本号不低于 CMake Tools 支持的最低版本（3.10+）。
三、手动触发 CMake 配置并选择正确的 Kit
CMake Tools 依赖 Kit（编译器+环境组合）完成配置。若未显式选择 Kit，扩展可能默认使用空或不兼容的配置，导致 configure 失败。
1、按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS） 打开命令面板。
2、输入并选择 CMake: Configure。
3、当提示选择 Kit 时，从列表中选取含 GCC、Clang 或 AppleClang 标识的有效项；若列表为空，先执行“CMake: Scan for Kits”。
4、观察底部状态栏是否出现 Configuring... Done 提示，并确认输出面板中 CMake Output 标签页无 ERROR 级日志。
四、指定构建类型与构建目录路径
CMake Tools 默认在 build/ 子目录执行 out-of-source 构建。若该路径被占用、权限不足或与自定义路径冲突，将导致构建失败或行为异常。
1、打开命令面板，执行 CMake: Set Build Type，从中选择 Debug、Release 或其他有效类型。
2、执行 CMake: Set Build Directory，输入绝对路径（如 /Users/username/project/build-debug），确保父目录可写且不含中文或空格。
3、再次执行 CMake: Configure，确认新路径被识别并在状态栏显示对应构建类型。
五、重置 CMake 缓存并清除构建产物
当 CMakeCache.txt 损坏、生成器参数变更或旧构建产物干扰新配置时，需彻底清理缓存与中间文件，避免残留状态引发不可预测错误。
1、执行命令面板中的 CMake: Delete Cache and Reconfigure。
2、在弹出的确认对话框中点击 Yes，等待清理完成。
3、若仍报错，手动进入构建目录，执行 rm -rf *（macOS/Linux）或删除全部内容（Windows），再重新触发 Configure。
