最常卡在语法拼写错误、路径写错或变量未展开这三类问题上，它们直接导致cmake配置中断，连构建系统都生成不了；致命空项目因漏project()命令使add_executable等全部失效，路径须拼写正确且变量必须用${}展开，源文件需真实存在并显式列出，option修改后须删cmakecache.txt才能生效。
排查CMakeLists.txt报错时，最常卡在语法拼写错误、路径写错或变量未展开这三类问题上，它们直接导致CMake配置中断，连构建系统都生成不了。
致命空项目：漏掉project()命令
第一步：打开CMakeLists.txt，检查文件开头是否紧接在cmake_minimum_required()之后就调用了project()命令。
第二步：确认project()是字面量调用，不能被if包裹、不能加引号、不能写成PROJECT()或Project()——CMake对这个命令大小写和调用方式极其敏感。
第三步：补上合法的project声明，例如：project(MyApp LANGUAGES CXX)。这一步不可跳过，【缺少project()会导致add_executable等所有后续命令全部失效】，CMake会直接报“No project command is present”并退出。
路径拼写与变量展开错误
方法一：检查所有路径字符串是否拼写正确，比如include_directories(../incude)中的incude是明显拼写错误，应为include。
方法二：凡涉及变量的路径，必须用${}包裹，例如include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)。写成include_directories(CMAKE_CURRENT_SOURCE_DIR/include)会被当作字面路径，CMake会去查找名为“CMAKE_CURRENT_SOURCE_DIR”的子目录，而非展开变量值。
方法三：跨子目录引用时，优先使用${CMAKE_CURRENT_SOURCE_DIR}而非硬编码相对路径。例如在src/CMakeLists.txt中要包含上级include/，应写include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../include)，而不是include_directories(../include)——后者在某些IDE或CI环境中因工作目录不同而失效。
CMake 4.3.2 Windows x86_64 历史版本安装包，适合旧项目兼容、构建环境回退、CMakeLists.txt 迁移验证、Visual Studio/Ninja/Makefile 生成器测试和 C/C++ 项目维护。
源文件列表不匹配
检查add_executable()或add_library()中列出的源文件名，是否真实存在于对应路径下。CMake不会自动模糊匹配或忽略缺失文件，只要写了一个不存在的main.cpp，就会报Cannot find source file "main.cpp"。
这一步操作起来很简单，直接在终端执行ls -l main.cpp确认文件存在即可。如果文件在子目录里，比如src/main.c，就必须写全路径，不能只写main.c。
注意：【SRCS变量必须显式赋值并用${}展开，如set(SRCS src/main.c) → add_executable(app ${SRCS})】，否则CMake无法识别源文件列表。
组件依赖声明遗漏
在ESP-IDF等框架中，若使用了LCD驱动但只写了REQUIRES esp_lcd，却没加esp_driver_gpio，编译时会在链接阶段失败，报类似undefined reference to 'gpio_set_direction'的错误。
解决方法是回溯代码中实际调用的API所属模块，把所有底层依赖组件一次性列全，例如：REQUIRES esp_lcd esp_driver_gpio freertos。漏掉任意一个，都可能导致头文件能包含、函数声明能通过，但最终链接失败。
CMakeCache.txt干扰option生效
当你修改了CMakeLists.txt中的option(ENABLE_LOG ON)并想切换开关时，如果之前已运行过cmake，CMakeCache.txt会缓存旧值，新设置不会生效。
必须删除构建目录下的CMakeCache.txt，再重新运行cmake配置命令。这一步不可省略，否则无论你怎么改option默认值，CMake都读取缓存里的旧状态。
