当前唯一推荐方式是在模块级app/build.gradle的android块中用ndkVersion显式指定完整版本字符串（如"25.2.9519653"），该值必须与SDK Manager已安装版本完全一致，且与Gradle插件版本强兼容，否则构建失败。
直接在 build.gradle 里用 ndkVersion 指定，这是当前唯一推荐方式
Android Gradle 插件 3.5.0+ 已废弃 ndk.dir 和 android.ndk 块（旧 experimental 插件语法），也不再读取 local.properties 中的 ndk.dir。现在必须通过 android { ndkVersion "25.2.9519653" } 显式声明版本。
这个值不是路径，而是 NDK 的完整版本字符串，比如 25.2.9519653 或 26.1.10909125。它必须和你已安装的 NDK 版本完全一致，否则构建会失败并提示 NDK version is unknown 或 NDK not found。
-
ndkVersion必须写在模块级app/build.gradle的android { }块内，不能放在 project 级或defaultConfig里 - 如果未安装对应版本，Gradle 不会自动下载，只会报错；需先通过 SDK Manager 安装该版本
- 多个 module 共享同一份 NDK，但每个 module 可独立指定
ndkVersion，不冲突
为什么不能只靠 local.properties 或环境变量
ndk.dir 在 local.properties 中已被标记为废弃（deprecated），AGP 8.0+ 会直接忽略它；ANDROID_NDK_HOME 环境变量仅影响命令行工具（如 ndk-build），对 Gradle 构建链无作用。
常见误操作是：手动解压 NDK 到某路径，然后在 local.properties 写 ndk.dir=/path/to/ndk，以为这样就能生效。结果 Sync 成功但编译时找不到 toolchain、clang 找不到、或 ABI 编译失败——因为 Gradle 根本没读这个路径。
- SDK Manager 安装的 NDK 默认放在
$ANDROID_SDK_ROOT/ndk/，结构为android-sdk/ndk/25.2.9519653/ - 如果你硬要用自定义路径，必须确保该路径下存在
source.properties文件（含Pkg.Revision字段），否则 Gradle 无法识别为合法 NDK - 环境变量
ANDROID_NDK_HOME仅用于 CMake 命令行调用或 CI 脚本，不影响 Android Studio 的 Gradle 同步
ndkVersion 和 Gradle 插件版本强绑定，配错就编译失败
不是所有 NDK 版本都能和任意 AGP 兼配。例如 AGP 8.4.x 要求最低 NDK 22.1.7171670，若你强行写 ndkVersion "21.4.7075529"，Sync 阶段就会报 Incompatible NDK version 并中断。
官方兼容表明确列出每版 AGP 对应的「最低支持」和「推荐稳定」NDK 版本。实际项目中建议：
- 优先选 SDK Manager 中标有
Recommended的版本（如25.2.9519653） - 团队统一使用一个
ndkVersion字符串，写死在build.gradle里，避免本地环境差异 - CI 构建前确认
ANDROID_SDK_ROOT下已预装对应 NDK 目录，否则gradlew build会卡住或失败
验证是否真的生效，别信 Sync 成功就完事了
Sync 成功 ≠ NDK 版本已正确加载。真正生效要看 native 编译阶段输出的日志，以及生成的 .so 文件 ABI 和符号信息。
最可靠的方式是在 Terminal 中运行：
./gradlew assembleDebug --info | grep -i "ndk\|toolchain"
你会看到类似这样的输出：
Using NDK at /Users/me/Library/Android/sdk/ndk/25.2.9519653 Using toolchain 'llvm' with target 'aarch64-linux-android21'
- 如果输出的是
ndk-bundle或其他路径，说明你还在用旧版配置，或者ndkVersion值拼错了 - 如果没看到
Using NDK at ...，大概率是ndkVersion字符串和已安装版本不匹配 - 最终生成的
app/build/intermediates/merged_native_libs/debug/out/lib/arm64-v8a/libnative-lib.so可用file或readelf -A查看其编译器标识，反向验证 NDK 实际使用版本
最容易被忽略的一点：NDK 版本一旦指定，就锁死了整个 native 构建链的 toolchain、sysroot、C++ STL 行为。哪怕只是改了一个 cppFlags，背后用的 clang、linker、libc++ 都由这个 ndkVersion 决定。所以别把它当成一个“可选字段”，而要当作和 compileSdkVersion 同等级的关键基础设施配置。
