externalNativeBuild块必须在defaultConfig和android顶层同时配置：前者指定CMake参数（如cppFlags、abiFilters），后者声明CMakeLists.txt路径及版本；缺一不可，否则原生构建不触发。
Gradle 中 externalNativeBuild 块必须配对出现
只在 defaultConfig 里写 externalNativeBuild，却不加顶层的同名块，CMake 就不会被触发——这是新手最常漏掉的一处。Gradle 要求两者共存：一个声明「怎么构建」，一个声明「构建哪个脚本」。
正确写法是两处都要有：
android { defaultConfig { externalNativeBuild { cmake { ... } } } }android { externalNativeBuild { cmake { path "CMakeLists.txt" } } }
缺后者，Gradle 根本不知道 CMake 脚本在哪；缺前者，它不知道该用什么参数调 CMake。Android Studio 有时会自动补全其中一处，但不能依赖它。
cmake.path 必须是相对于 module 根目录的路径
path 参数不是绝对路径，也不是相对于项目根目录，而是相对于当前 build.gradle 所在 module 的根目录。比如你的 CMakeLists.txt 放在 app/src/main/cpp/ 下，那就要写 path "src/main/cpp/CMakeLists.txt"，而不是 "app/src/main/cpp/CMakeLists.txt" 或 "/src/main/cpp/CMakeLists.txt"。
常见错误现象：Cannot find CMakeLists.txt 或构建时完全跳过 native 步骤。检查路径是否拼错、大小写是否匹配（Windows 上不敏感，Linux/macOS/CI 环境上敏感）。
NDK 版本和 CMake 版本要手动对齐
Gradle 不会自动帮你选兼容的 CMake 版本。比如你装了 NDK r25，但 build.gradle 里写 version "3.6.0"，就可能遇到 Unknown argument -DANDROID_STL 这类报错——因为旧版 CMake 不认识新 NDK 的参数。
建议做法：
- 优先用 Android Studio SDK Manager 安装的 CMake（如
3.10.2或3.22.1），它们经过 Google 验证 - 在
build.gradle中显式指定版本：version "3.10.2" - 确认
local.properties里有有效的ndk.dir（或依赖 AGP 自动管理）
AGP 4.2+ 虽支持自动安装 NDK/CMake，但自动选的版本未必是你项目需要的——尤其当团队多人协作、CI 使用固定镜像时，版本漂移会导致构建不可重现。
abiFilters 在两个地方都要设，作用不同
defaultConfig.ndk.abiFilters 控制「打包进 APK 的 ABI 架构」；defaultConfig.externalNativeBuild.cmake.arguments 里的 -DANDROID_ABI=...（或通过 abiFilters 间接影响）才真正控制「编译哪些架构」。两者不一致，就会出现「编译了 armeabi-v7a，却把 arm64-v8a 的 so 打进了 APK」，或者反过来「APK 里没 so，运行时报 UnsatisfiedLinkError」。
稳妥做法是保持一致：
ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }externalNativeBuild { cmake { abiFilters 'armeabi-v7a', 'arm64-v8a' } }
注意：abiFilters 在 cmake 块里是 AGP 提供的快捷方式，底层仍会转成 -DANDROID_ABI 传给 CMake。如果同时用 arguments 手动传 -DANDROID_ABI，后者会覆盖前者。
