简介android-ndk-r25b-darwin.zip 是为 macOS 用户准备的 Android NDK r25b 工具包面向需要在 Android 工程中嵌入 C/C 原生代码的开发者广泛应用于高性能计算、图形渲染、游戏引擎等场景。它支持 JNI 互调、ndk-build 与 CMake 构建并提供多线程、内存管理、调试以及 APK 大小优化等开发要点的支持。解压后共 2000 个文件压缩包约 683.4 MB其中 1888 个 .h 头文件覆盖 ARM NEON、Vulkan、相机等 API 声明85 个 .py 脚本可用于构建或调试辅助另有 md、txt 等文档和 c/cpp 文件帮助理解配置。已有 403 人学习/下载适合具备一定 C/C 基础、希望深入原生层的读者。借助该包可迅速搭建 NDK 开发环境并在统一的工具链中编译生成 .so 库头文件与脚本也可作为日常查阅 JNI 声明和自动化构建的参考资料可有效提升原生模块开发效率。1. 一份 android-ndk-r25b-darwin.zip是 JNI 工程绕不开的版本锚点如果你维护过 2022 到 2023 年间的原生工程、接手过别人拷来的 Android SDK 目录、或者在 CI 服务器上遇到依赖包下载中断的窘境大概率会在内网盘或迁移包里见到这个文件名android-ndk-r25b-darwin.zip。它是 NDK r25b 在 macOS 平台上的完整分发归档涵盖 arm64-v8a、armeabi-v7a、x86、x86_64 四类 ABI 的交叉编译工具链对应 AGP 自动下载时最常见的版本目录 25.1.8937393。接下来的内容围绕这份 zip 展开r25b 在 NDK 版本序列中的定位、darwin 包与 Linux/Windows 包的差异、在 macOS 上从解压到产出 .so 的完整过程以及老工程迁移时最常见的几个坑。2. r25b 在 NDK 版本线里的真实坐标AGP 匹配与 darwin 包的边界2.1 为什么偏偏是 r25b 这个稳定点NDK r25 正式版发布于 2022 年r25b 是它的补丁版本。它常被看成“老工艺终点”原因是这个版本同时满足两件事工具链已经完全过渡到 clang/gcc 时代彻底翻篇但最低支持 API level 仍然保留着 32 位 ABI 可到 16 的旧口径。往后的 r26 把全 ABI 最低支持提升到 21很多还挂着 minSdkVersion 19 的存量项目就很难直接切过去。此外大量 AGP 7.3.x 到 8.0.x 工程默认的 NDK 版本写的就是 25.1.8937393。gradle 自动下载时会在本地 SDK 的 ndk/ 目录下创建同名文件夹本质上就是把这颗 zip 解压后的结构原样放好。离线环境或内网镜像场景里手动解开这份 darwin.zip 再放到对应目录比让 gradle 反复重试下载要省事得多。提示r25b 不是 NDK 目录里“越大越新”的版本它在 r24 与 r26 之间承担的是过渡稳定位。2023 年之前发布的企业级 SDK、金融与 IoT 厂商的 so 库多数编译基线就是它。2.2 用版本对照表确认兼容边界以下数据按各 release note 常见口径整理实际操作时以你的 AGP 与 SDK 组合为准NDK 版本目录版本号默认编译器32 位 ABI 最低 API64 位 ABI 最低 API常见 AGP 搭配r23b23.1.7779620clang 121621AGP 7.1/7.2r2424.0.8215888clang 141621不常见r25b25.1.8937393clang 14.0.71621AGP 7.3/7.4/8.0r26b26.1.10909125clang 162121AGP 8.2表中“最低 API”指编译链接时允许指定的最低 android- 平台级别。比如项目 build.gradle 里配了minSdk 19在 r26b 下编译就会遇到平台级别过低的报错而 r25b 可以正常工作。反过来如果你今天新建工程且没有历史包袱直接选 r26b 或更新版本即可没必要抱着 darwin.zip 不放。2.3 darwin 包的边界不止“Mac 可用”这么简单darwin 是 macOS 内核名这份 zip 解压后的工具链目录为 toolchains/llvm/prebuilt/darwin-x86_64。注意目录名里的 x86_64Intel Mac 可以直接执行Apple Silicon 上则依赖 Rosetta 2 转译首次执行 clang 时系统会提示安装对应运行环境之后编译速度比原生 arm64 工具链略慢但产物没有差别。常见的误用是把 darwin 包在 Linux 节点上解压然后 clang 报 Exec format error或者反过来把 linux 包拖到 mac 上跑。排查这类问题先看压缩包平台后缀与uname -m再去看工具链 prebuilt 目录名两个信息一对基本不会找错方向。3. macOS 上从 zip 到可用 NDK解压、校验与三项配置3.1 按 SDK 规范解压并归位Android SDK 对 NDK 的目录约定是$ANDROID_SDK_ROOT/ndk/版本号/r25b 对应的版本号是 25.1.8937393。只要解压后的目录名与 ndkVersion 对得上AGP 就能自动发现无需额外写死绝对路径。# 请按本机实际 SDK 位置修改 ANDROID_SDK_ROOT$HOME/Library/Android/sdk mkdir -p $ANDROID_SDK_ROOT/ndk unzip -q android-ndk-r25b-darwin.zip mv android-ndk-r25b $ANDROID_SDK_ROOT/ndk/25.1.8937393这里先建 ndk 根目录再解压出 android-ndk-r25b 文件夹最后重命名为版本号形式。用 mv 而不是直接解压到目标目录是为了保证 zip 内的根目录名与 AGP 期望的版本目录一致避免后续因目录名不匹配而触发“NDK not found”。3.2 环境变量、local.properties 与自检命令命令行编译时建议把下面两行写进 ~/.zshrc 或 CI 脚本顶部这是 macOS 上手工调 NDK 的最小环境配置export ANDROID_NDK_HOME$HOME/Library/Android/sdk/ndk/25.1.8937393 export ANDROID_NDK_ROOT$ANDROID_SDK_ROOT/ndk/25.1.8937393第一行是新工具链默认识别的变量第二行兼容老构建体系。随后可以做一次快速自检确认 clang 能正常加载目标平台$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/clang \ --targetaarch64-linux-android21 \ --sysroot$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/sysroot \ -v 21 | head -8--targetaarch64-linux-android21明确目标 ABI 与 API level 21--sysroot指向 NDK 自带的系统头文件与链接库。看到 clang 版本和 ld 路径正常输出说明工具链整体可用。对于 gradle 工程则需要在local.properties写sdk.dir...并在模块级 build.gradle 中声明ndkVersion 25.1.8937393。提示AGP 7.0 起已标记ndk.dir为废弃用法。交接老仓库时若看到 local.properties 里写了 ndk.dir建议迁移成 ndkVersion 声明否则后续升级 AGP 会先在这里出警告。3.3 校验 zip 完整性别等编译到一半才发现缺文件网络下载的 zip 或内网拷贝的归档建议先做一次哈希校验对照 NDK 发布页给出的 sha256 值shasum -a 256 android-ndk-r25b-darwin.zip手头没有官方哈希时还有一个更快的完整性动作直接跑ndk-build --version。$ANDROID_NDK_HOME/ndk-build --version这条命令会触发 NDK 加载工具链描述文件与预置脚本核心文件缺失时会在第一次运行就报出具体路径。先哈希后命令两份验证都过了这份 zip 才算真正变成可用 NDK。4. 用 r25b 出产物ndk-build 与 CMake 两条常用路径4.1 旧式工程Android.mk 与 ndk-build 的最小组合老一批 SDK 仓库还保留着 jni/Android.mk 的写法这类工程不需要 gradle 介入直接用 r25b 自带的 ndk-build 脚本即可。先准备一个最小的 Android.mk# jni/Android.mk LOCAL_PATH : $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE : hellojni LOCAL_SRC_FILES : hello.c include $(BUILD_SHARED_LIBRARY)然后执行编译命令$ANDROID_NDK_HOME/ndk-build \ APP_ABIarm64-v8a,armeabi-v7a \ APP_PLATFORMandroid-21 \ -j 8APP_ABI用逗号分隔不写默认编全部四种 ABIAPP_PLATFORM决定头文件与链接库的 API levelandroid-21 是既能覆盖 64 位设备又不过度放宽的常用档位。-j 8是并行任务数按 CPU 核数调整。产物会落在libs/abi/libhellojni.so。想查看完整编译命令加V1清理旧产物执行ndk-build clean。4.2 现代工程gradle 调起 CMake 的推荐配置现在更多工程走 CMake 路径。build.gradle 里需要同时声明 NDK 版本和 CMake 参数android { ndkVersion 25.1.8937393 defaultConfig { externalNativeBuild { cmake { cppFlags -stdc17 // 用 shared 版 STL避免多个 so 各自静态链接一份 libc 导致符号冲突 arguments -DANDROID_STLc_shared } } } externalNativeBuild { cmake { path src/main/cpp/CMakeLists.txt } } }对应的最小 CMakeLists.txtcmake_minimum_required(VERSION 3.22.1) project(hellojni) add_library(hellojni SHARED hello.cpp) # 链接系统库log 用于 __android_log_printandroid 用于 JNI 相关 API target_link_libraries(hellojni log android)两处参数需要展开说明。-DANDROID_STLc_shared决定 C 运行时以同名 libc_shared.so 打进 APK 而非静态合并进产物工程里有多个 so 相互调用时选 shared 几乎是必须的否则各自静态链接后运行时容易出现重复符号或 typeinfo 不一致。target_link_libraries中链接 log 与 android 是 JNI 工程常规操作前者提供日志输出后者提供 native 侧访问系统能力的入口。配置完后直接执行./gradlew :app:assembleDebug产物在app/build/intermediates/merged_native_libs/debug/out/lib/下。验证方式就是确认每个 ABI 子目录都有对应 .so再用上一章的自检命令确认 clang 版本确实来自 r25b 目录。4.3 常用命令与参数对照目标命令或配置说明只编指定 ABI在 cmake 块加abiFilters arm64-v8a比注入编译属性更可控适合 CI清理 gradle 与 CMake 缓存./gradlew clean换 NDK 版本后必须执行一次查看 ndk-build 完整日志ndk-build V1定位头文件路径与链接顺序用切换 STL 实现-DANDROID_STLc_shared/c_static单个 so 且无跨 so 符号交互才用 static有一点常被忽略abiFilters和 ndk-build 的APP_ABI不要同时在不同位置写两份来源不同的列表否则构建系统会以较严格的一侧为效率优先反而掩盖掉某些 ABI 的真实编译错误。5. 换个 NDK 就崩的排查路径与 darwin 包实战细节5.1 三个高频报错的快速定位报错原文节选常见原因处理方式Exec format error在 Linux 节点上解压了 darwin 包或反了换同版本对应平台的 zip重新配置路径Unsupported option -faddrsigMakefile 里还留着 clang 3.x 时代的参数清理与重定位相关的历史 flags只留必要优化项No rule to make target ...liblog.soAPP_PLATFORM 指定过低或缺target_link_libraries提升 APP_PLATFORM 到 android-21补 log 依赖这三个问题都不是 r25b 特有但在老工程换 NDK 时最先炸出来。5.2 多 NDK 版本共存的切换技巧把 r25b 和更高版本全部放在$ANDROID_SDK_ROOT/ndk/下目录间互不干扰。命令行切版本时不要逐个 export用函数更省事use_ndk() { export ANDROID_NDK_HOME$HOME/Library/Android/sdk/ndk/$1 export ANDROID_NDK_ROOT$ANDROID_NDK_HOME echo current: $ANDROID_NDK_HOME } use_ndk 25.1.8937393切换后补一句ndk-build --version或clang --version确认落点比靠 echo 输出更可靠。5.3 一次性确认 so 的真实 ABI产物出来之后用 r25b 自带的 llvm-readelf 做最后一道验证$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-readelf \ -h path/to/libhellojni.so | grep Machine输出里EM_AARCH64对应 arm64-v8aEM_ARM对应 32 位 armeabi-v7a。搭配llvm-objdump --tripleaarch64-linux-android21 -d反汇编一段函数还能进一步核对编译目标的 CPU 架构等级。这个组合在团队切换 NDK 版本后做产物对比时非常顺手不需要依赖真机就可以把版本兼容性问题锁定到单条指令级别。本文还有配套的精品资源点击获取