project()必须在CMakeLists.txt最前面，因其顺序执行且初始化编译器、标准及内置变量；位置错误会导致add_executable等命令报错。
为什么 CMakeLists.txt 里 project() 必须在最前面
因为 CMake 解析是顺序执行的，project() 不仅声明项目名和语言，还会隐式设置编译器、标准（如 CXX_STANDARD）、内置变量（如 CMAKE_CXX_COMPILER_ID）。如果它出现在 find_package() 或 add_executable() 后面，后续命令可能用到未初始化的变量，导致 Unknown CMake command "add_executable" 这类报错。
实操建议：
立即学习“C++免费学习笔记（深入）”；
-
project()必须是CMakeLists.txt中第一个有效命令（注释和空行除外） - 显式指定语言和标准更稳妥：
project(myapp LANGUAGES CXX VERSION 1.0.0)，避免依赖隐式推断 - 跨平台时别写死编译器路径，让 CMake 自动探测；若需强制，用
-DCMAKE_CXX_COMPILER=clang++命令行传入，而非在CMakeLists.txt里硬编码
Windows 上用 MinGW 编译却提示 Cannot find source file: main.cpp
这不是文件没找到，而是 CMake 没识别出源文件编码或路径分隔符问题——尤其当项目含中文路径，或 add_executable() 中用了反斜杠 \。CMake 内部统一用正斜杠 /，Windows 下混用会导致路径解析失败。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 所有路径一律用正斜杠：
add_executable(app src/main.cpp src/utils.cpp)，别写src\main.cpp - 确保
main.cpp文件真实存在且编码为 UTF-8（无 BOM），BOM 会干扰 CMake 解析 - MinGW 构建前先清理缓存：
rm -rf build/ && mkdir build && cd build && cmake -G "MinGW Makefiles" ..，避免旧缓存残留干扰 - 检查
cmake --version是否 ≥ 3.10：老版本对 MinGW 的find_package(Threads)支持不全
Linux/macOS 下 std::filesystem 链接失败：undefined reference to std::filesystem::status
这是链接器没加 -lstdc++fs，不是头文件没包含。C++17 的 std::filesystem 在 GCC 8–11 是实验性实现，必须显式链接静态库；Clang 则需 -lc++fs（macOS）或 -lstdc++fs（Linux）。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 不要只靠
target_compile_features(app PRIVATE cxx_std_17)，还得配链接库：target_link_libraries(app PRIVATE stdc++fs) - 更兼容的做法是用
find_package(Threads REQUIRED)+target_link_libraries(app PRIVATE Threads::Threads)替代硬编码 - macOS 上 Clang 默认不启用
std::filesystem，需额外加编译选项：target_compile_options(app PRIVATE -stdlib=libc++) - 用
cmake -DCMAKE_BUILD_TYPE=Debug ..而非默认构建，方便定位链接阶段错误
交叉编译 Android 时 find_package(OpenCV) 总失败
因为 find_package() 默认查系统路径（/usr/local、/opt），而 Android NDK 的 OpenCV 是预编译的独立包，必须手动指定 CMAKE_PREFIX_PATH 指向它的 build/install 目录。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 下载 OpenCV for Android，解压后找到
OpenCV-android-sdk/sdk/native/jni，把build/install加进路径：cmake -DCMAKE_PREFIX_PATH=/path/to/opencv/build/install -DANDROID_ABI=arm64-v8a .. - 禁用 OpenCV 的自动查找逻辑：
set(OpenCV_FIND_REQUIRED OFF)，改用find_path()和find_library()手动定位头文件和libopencv_core.a - Android NDK r21+ 默认用 libc++，确保 OpenCV 编译时也用相同 STL，否则出现
undefined reference to __cxa_throw - 别在
CMakeLists.txt里写include_directories(/path/to/opencv/include)，优先走find_package()+target_include_directories()，否则跨平台切换时容易漏改
跨平台 CMake 最难的不是语法，是每个平台对“标准”的理解差得远——Windows 的路径、Linux 的链接器、Android 的 ABI 和 STL 绑定，都得单独验证。一个 find_package() 调用背后，往往要试三套路径、两版 CMake、四种编译器组合。
