“No CMAKE_CXX_COMPILER could be found”报错主因是编译器未安装、PATH未配置或CMake缓存残留，需依次检查g++/clang++可用性、系统PATH、CMakeCache.txt清理及必要时手动指定编译器路径。
“No CMAKE_CXX_COMPILER could be found” 这类报错，90% 是编译器没装、没配好，或 CMake 缓存残留导致的误判，不是 CMake 本身坏了。
找不到 C++ 编译器（No CMAKE_CXX_COMPILER could be found）
这是 CMake 配置阶段最常卡住的第一道门槛。现象是 cmake .. 直接报错退出，连 project() 都没执行完。
- 先确认
g++或clang++是否真能运行：g++ --version；如果命令未找到，说明编译器根本没装——Ubuntu/Debian 下跑sudo apt install build-essential即可 - Windows 用户用 MinGW-w64，必须把
mingw64\bin加进系统PATH，且重启终端生效；VS Code 中还要在命令面板执行CMake: Select a Kit手动选中对应工具链 - 即使编译器存在，CMake 也可能因旧缓存误判：删掉构建目录下的
CMakeCache.txt和整个CMakeFiles/目录再重试 - 极端情况（如交叉编译或容器环境），可强制指定：
cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++ ..
find_package 找不到库（Could NOT find XXX）
典型错误信息形如 Could NOT find OpenCV (missing: OpenCV_DIR) 或 By not providing "FindXXX.cmake" in CMAKE_MODULE_PATH...，本质是路径未对齐。
- 不要依赖系统包管理器“装了就自动能找到”——
apt install libopencv-dev后，CMake 仍可能找不到，因为OpenCVConfig.cmake不在默认搜索路径里 - 优先查清库的配置文件在哪：
find /usr -name "OpenCVConfig.cmake" 2>/dev/null，然后手动传给 CMake：cmake -DOpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4 .. - 更鲁棒的做法是用
FetchContent拉源码编译（尤其适合 CI 或无 root 权限场景）：FetchContent_Declare(opencv GIT_REPOSITORY https://github.com/opencv/opencv GIT_TAG 4.10.0)，再FetchContent_MakeAvailable(opencv) - 注意大小写：
find_package(OpenCV)和find_package(opencv)在某些旧版 CMake 下行为不同；模块名必须与FindXXX.cmake或XXXConfig.cmake文件名严格一致
头文件或源文件路径错误（file not found / Cannot find source file）
编译时报 fatal error: 'utils.h' file not found，或 CMake 配置时报 Cannot find source file: "src/main.cpp"，根源几乎全是路径拼写或作用域问题。
-
include_directories()已过时，改用target_include_directories(my_target PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)；PRIVATE/INTERFACE/PUBLIC 语义必须匹配实际使用场景 - 用
file(GLOB SOURCES CONFIGURE_DEPENDS "src/*.cpp")替代手写列表，CONFIGURE_DEPENDS关键字不能省——否则新增 .cpp 文件后不重新 cmake 就不会被纳入编译 - 绝对路径最稳：
set(SRC_FILE ${CMAKE_CURRENT_SOURCE_DIR}/src/utils.cpp)，避免相对路径在子目录add_subdirectory()时失效 - 检查是否误用了
${CMAKE_CURRENT_BINARY_DIR}当作源码路径——那是构建目录，放的是中间文件，不是源码
变量值为空或意外（message 输出为空 / MY_VAR 未定义）
message("MY_VAR = ${MY_VAR}") 打印出 MY_VAR = ，不代表变量不存在，而是它在当前作用域不可见或被覆盖。
- CMake 变量默认是**函数局部作用域**：在
function()里 set 的变量，外部看不到；必须加PARENT_SCOPE才能透出：set(MY_VAR "ok" PARENT_SCOPE) - 大小写敏感：
MyVar、myvar、MYVAR是三个不同变量；project()定义的PROJECT_NAME是大写，别写成project_name - 调试时别只看一个变量，用批量 dump：
get_cmake_property(_vars VARIABLES); foreach(_v IN LISTS _vars) message(STATUS "${_v}=${${_v}}") endforeach() - 避免在
if()中直接用未定义变量：if(NOT MY_VAR)会静默失败；应先if(DEFINED MY_VAR)再判断值
真正难缠的不是报错本身，而是 CMake 的“延迟求值”和隐式作用域——同一行 set() 在 function 内外效果完全不同，同一个变量名在不同 add_subdirectory() 层级可能指向完全不同的值。动手前多跑一次 message(STATUS ...)，比猜半天快得多。
