★ FEATURED ARTICLE 开头做Cocos Creator Android开发的朋友几乎都会在第一次打APK的时候被NDK折腾一遍。无论是那句“NDK not configured. Download it with SDK manager.”还是实际编译到一半蹦出来的各种clang错误本质都是版本没对上、路径没配对造成的。这篇博文就把Cocos Creator Android打包时NDK版本选择与配置这件事彻底讲透覆盖2.x到3.x各版本、构建面板到Gradle命令行的完整配置流程帮你少走弯路一次就把APK打出来。1. 内容整体设计与思路拆解1.1 NDK在这套打包流程里到底扮演什么角色Cocos Creator开发的项目并不是纯Java/Kotlin工程引擎底层是C写的尤其是物理、渲染、原生平台桥接这些模块全部要走Native编译。Android Studio自带的JVM只能编译Java代码遇到C代码就必须调用NDKNative Development Kit里的交叉编译工具链把C源码编译成各ABI架构arm64-v8a、armeabi-v7a、x86_64等对应的.so动态库再和Java层一起打包成APK。另外你自己集成的一些第三方SDK如果提供了C/C源码或者需要JNI桥接同样离不开NDK。所以打包APK时只要构建脚本里含有C编译任务Gradle就会在configure阶段调用NDK。换句话说NDK不是可有可无的插件而是Cocos Creator Android构建链的必经一环。我之前见过有人把NDK下载了却不配置Cocos里的路径结果构建面板直接报错也有人版本选得对但路径填错Gradle还是会跑到系统默认目录去找。1.2 为什么版本选择是“第一步的命门”很多人觉得“随便装个最新版NDK不就行了”但实际项目中Cocos Creator引擎、AGPAndroid Gradle Plugin、Gradle、NDK四者之间存在一整套版本约束关系。引擎侧会依赖特定范围的NDK APIAGP侧的构建逻辑也会检查NDK版本特别是新版AGP会直接校验“preferred NDK version”版本不一致就拒绝往下走。举个例子你创建了一个Cocos Creator 3.8项目默认用的Gradle是7.xAGP可能是7.4左右这种情况下如果装一个NDK r27很可能在Gradle配置阶段就报“NDK did not have a source.properties file”或者“unsupported NDK version”。反过来如果装太老的NDK r16编译器又无法解析引擎里较新的C标准直接出现大量“undefined reference”。所以这个版本不能随心所欲必须跟着项目模板走。1.3 我的问题排查思路四步定位法遇到NDK相关报错我一般按固定思路来第一步看Cocos Creator具体版本和构建模板里Gradle/AGP的版本第二步根据版本对应表确定需要哪个NDK主版本并尽量选该主版本里偏新的小版本第三步确认NDK实际安装路径和构建脚本使用的路径一致第四步用一个空项目做一次完整Gradle编译验证环境无误后再打正式包。这套思路基本能覆盖95%的NDK配置问题。后面我写的所有内容也都是按这个思路展开的。别一上来就重装Android Studio或者换个JDK那都是最后手段。2. 核心细节解析与实操要点2.1 Cocos Creator、Gradle、AGP、NDK的版本联动关系Cocos Creator从2.x到3.x每个版本发布时都会带一个默认构建模板模板里的Gradle和AGP版本是固定好的。你的NDK版本必须能兼容这两个版本。这条链路的关系是Cocos Creator选定Gradle版本Gradle决定AGP的可用范围AGP再去校验NDK版本。任何一个环节脱节都会最终表现在NDK相关报错上。我在本地电脑上维护了一张“版本对照表”基本逻辑是这样的Cocos Creator 2.4.x默认Gradle 6.x、AGP 4.x对应的NDK最好是r21系列Cocos Creator 3.0到3.4Gradle升级到了6.x/7.xAGP到了5.x/7.xNDK推荐r21到r22Cocos Creator 3.5到3.8Gradle 7.x/8.xAGP 7.x/8.xNDK推荐r23c或者r25bCocos Creator 3.8.5及之后的新模板部分版本推荐用NDK r26b或r25c具体以Creator构建日志里提示的preferred NDK version为准。这个表我用了很久除了个别小版本差异基本没翻过车。2.2 一份“照着选就行”的NDK版本清单这里我把经验直接列成一张可参考的清单。平时打包遇到问题先拿这张表对一遍比自己瞎试快得多。Cocos Creator版本推荐NDK版本备注2.4.0 - 2.4.12r21e / r21d老项目稳定首选3.0.0 - 3.4.2r21e / r22b部分模板用r21c也能编译3.5.0 - 3.7.3r23c / r23bgradle 7.x默认配套3.8.0 - 3.8.4r23c / r25b注意AGP 8.x会校验小版本3.8.5及以上r25b / r26b新模板自动下载r25b最常见注意这里说的是“推荐”不是“唯一”。因为Cocos官方其实允许你在build.gradle里手动指定ndkVersion只要那个版本本身存在且兼容C编译就行。但为了少踩坑优先照着官方模板默认值来是最稳妥的。2.3 ABI架构过滤与包体大小控制另一个容易被忽略的NDK细节是ABIApplication Binary Interface过滤。默认情况下Gradle会把所有ABI都编译出来包括真机上完全用不到的x86和x86_64这样打出来的APK体积会大很多而且模拟器架构并不影响发布。我一般会在项目里做一次ABI精简比如只保留arm64-v8a如果你还有老设备再加一个armeabi-v7a。实现方式是在native工程的build.gradle里配置android { defaultConfig { ndk { abiFilters arm64-v8a, armeabi-v7a } } }这个配置会直接影响NDK的编译目标能大幅减少编译时间和产出包体。要注意的是如果你接了带.so文件的第三方SDK务必确认对方的库覆盖了你保留的ABI否则运行时加载.so会直接抛找不到库的异常。2.4 为什么不要盲目追逐NDK最新版本每当我看到新手装了最新的NDK r27然后抱怨Cocos打包各种报错都会觉得这坑踩得太冤了。NDK更新频率并不快但它更新时往往会移除旧的平台API、修改默认工具链、升级C标准库版本而这些变化不会同步到Cocos构建模板里。AGP对NDK版本有弱校验弱校验只警告不阻断但C编译层面的不兼容是硬性的只能在报错时慢慢改。Cocos的项目模板在发布时已经用特定版本的NDK完整跑过一遍测试所以“跟随模板”是最省心的选择。等到你确实需要更高NDK来支持某个新特性再自己手动升级并且这个时候要有心理准备做源码层面的适配。3. 实操过程与核心环节实现3.1 第一步确认当前项目的Cocos Creator与构建模板版本在配置NDK之前先弄清楚你用的Cocos Creator确切版本。打开Cocos Creator编辑器菜单栏选择“关于”就能看到版本号。3.x版本还可以直接看项目目录下的package.json里creator字段。然后进入native工程的根目录找到build.gradle和gradle-wrapper.properties分别确认AGP版本和Gradle版本。这两个文件里的版本号决定了你NDK应该选在哪一个区间。很多报错的根源就是用户改了Cocos Creator版本但原生工程模板还停留在旧版结果环境不一致。3.2 第二步安装正确的NDK版本安装NDK有两条路径我分开说清楚。第一条通过Android Studio的SDK Manager安装。打开Android Studio进入SDK Manager的SDK Tools标签页勾选NDKSide by side旁边的Show Package Details然后选择你需要的具体版本比如27.0.12077973对应r25b、23.2.8568313对应r23b等点击Apply下载。这种方式最省事Android Studio会自动把NDK放到SDK目录下的ndk/子目录里Gradle通过SDK定位时能自动发现。第二条从Android开发者官网直接下载NDK压缩包手动解压到任意目录。这种方式适合没有Android Studio、只依赖命令行构建的人。下载时要看清版本列表里的版本号比如r23c对应的包名是android-ndk-r23c-windows.zip。解压之后把这个目录路径记好后面配置路径用。我平时更推荐第二种方式因为路径可以自己控制不容易出现“系统装了但在另一个SDK根目录下找不到”的问题。但无论如何安装完之后最好检查一下NDK目录里有没有source.properties文件这个文件的存在性是Gradle识别NDK合法性的关键。3.3 第三步让Cocos Creator和Gradle都能找到NDK这一步是绝大多数人卡住的地方。Cocos Creator构建APK时从构建面板到Gradle脚本一共涉及四个位置的NDK配置。第一个位置是Cocos Creator编辑器。打开“项目”-“项目设置”-“构建发布”或者在构建面板里的“原生”选项卡能看到Android相关设置项其中有NDK路径。点击右侧文件夹图标选择你NDK解压后的目录。注意这里的路径要精确到包含source.properties的那一层比如D:\Android\Sdk\ndk\23.2.8568313。第二个位置是原生工程的local.properties文件。打开native/engine/android/local.properties里面通常有sdk.dir和ndk.dir两个配置项。有的模板ndk.dir是可选的但手动加上更保险sdk.dir/path/to/your/sdk ndk.dir/path/to/your/ndk第三个位置是native工程里的gradle.properties。有些Cocos模板会在这里预留android.useDeprecatedNdk或者android.ndkVersion占位你需要手动指定android.ndkVersion23.2.8568313注意gradle.properties里android.ndkVersion要填完整版本号而不是r23c这种缩写。如果你不清楚完整数字版本号可以在NDK解压目录的source.properties里查看Pkg.Revision字段这个字段的值就是要填的内容。第四个位置是module级的build.gradle。有些新模板会直接在android块里写死ndkVersion例如android { ndkVersion 23.2.8568313 }如果这里已经写了一个版本但和你安装的不同优先改成你实际安装的版本。这四个位置全部对齐之后Gradle就不会因为找不到NDK而报“NDK not configured”了。3.4 第四步执行一次完整构建验证配置生效配置完之后不要急着回Cocos Creator点构建先在命令行里做一次验证。进入native/engine/android目录执行gradlew.bat assembleRelease这条命令会触发完整Gradle构建流程。如果NDK配置正确Gradle会在TASK列表里出现externalNativeBuild相关的编译任务控制台滚动的内容会包含clang编译C的日志。看到BUILD SUCCESSFUL之后再回头用Cocos Creator构建面板出包基本一把过。在Windows上执行gradlew.bat时常见的坑是cmd控制台环境变量没同步导致找不到Java或者SDK。可以在命令行里先执行echo %JAVA_HOME% echo %ANDROID_HOME%确认两个变量都指向正确路径后再继续否则后面报错容易跟NDK混在一起。3.5 补充命令行方式打包时的NDK指定如果你走的是命令行一键打包流程比如使用Cocos Creator的命令行工具cocos build -p android --apk这种情况下Cocos Creator会把编辑器里的NDK配置带入构建脚本但前提是你在项目设置里已经填好。命令行构建时它会重新生成native工程并覆盖local.properties所以如果你手动改过local.properties请先确认编辑器里的NDK路径也正确再执行命令。这里最容易犯的错误就是只改了native工程里的配置但编辑器里的还是空结果命令行一跑又回到初始状态。这类问题多发生在自动化打包环境里比如公司在CI服务器上配置打包任务。CI环境没有图形界面Cocos Creator还是能通过命令行读项目设置里的NDK路径把编辑器配置项保存好CI流程复用同一个项目配置就不会出问题。4. 常见问题与排查技巧实录4.1 最经典的报错NDK not configured这个报错的原话一般是“NDK not configured. Download it with SDK manager. Preferred NDK version is 23.2.8568313”。核心原因是Gradle在构建时找不到任何可用的NDK这里“preferred NDK version”是构建模板期望的版本号不是可选项。处理思路很简单要么去SDK Manager装上这个版本要么手动下载这个版本并把ndk.dir或android.ndkVersion指到它。有些老教程会让你直接修改build.gradle把ndkVersion改成你已有版本这条路也行但前提是已有版本和模板兼容。上面步骤里提到的四个位置检查一遍基本就能解决。我自己的习惯是尽量安装“preferred NDK version”而不是改模板这样后续升级Cocos Creator少一点麻烦。4.2 报错提示Preferred NDK version与实际不符比“NDK not configured”更隐蔽的一个报错是“NDK version X is not supported for this project. Minimum supported version is Y.”这时候要看你项目模板的AGP版本如果是AGP 7.4以上它支持的最低NDK版本会跟着调整。旧NDK r15、r16在AGP 7.x中已经无法通过了因为AGP要求NDK必须使用clang工具链而老版本NDK默认编译器不是clang。这时候你要么升级NDK要么把AGP版本降到对应NDK支持的区间。我建议直接升级NDK不要为了迁就NDK去改项目里的AGP因为AGP还同时约束Gradle版本和编译SDK版本牵一发动全身。4.3 C编译阶段的奇奇怪怪报错如果Gradle识别NDK成功但编译C时挂掉比如“undefined reference to std::__1::...”这往往是NDK版本和项目源码用到的C标准库不一致导致的。新NDK默认使用libc老项目可能还是stlport或gnustl编译时库的选择就崩了。解决方法是先看Cocos项目里有没有Application.mk或CMakeLists.txt里面有APP_STL或ANDROID_STL的设置。老版本模板可能写的gnustl_static但新版NDK里已经没有这个库了需要改成c_static。同样如果发现编译器参数里带了-fexceptions这类旧式指定也要看是否还在NDK工具链支持范围内。这一类的排查需要懂一点C构建知识但大多数人遇到都是因为项目模板太老解决办法就是升级Cocos Creator到较新版本或者手动改STL类型。4.4 构建时下载依赖超时或者卡死的处理NDK配置好了但Gradle构建时还会从Maven仓库下载大量依赖网络不好经常卡住有时候一次构建半小时下不完。第一次遇到这种情况别急着换NDK先检查gradle-wrapper.properties里的distributionUrl是不是被墙了可以换成国内可用的Gradle镜像地址。另外在项目的build.gradle里把Maven仓库也换成国内镜像源速度会明显改善。如果构建已经跑起来但中途某一个依赖反复下载失败建议在gradle.properties里加上org.gradle.jvmargs-Xmx4096m org.gradle.daemonfalse前者加大内存避免编译过程中OOM后者避免Gradle守护进程缓存异常导致的奇怪问题。4.5 常见问题速查表现象常见原因解决办法NDK not configuredNDK未安装或路径未配置安装preferred版本并配好路径Preferred NDK version 报错NDK版本与模板要求不符安装模板期望版本或改ndkVersion编译时clang秒退或大量报错NDK版本过旧或C STL不匹配换推荐NDK检查APP_STL设置APK体积过大ABI编译目标过多配abiFilters精简ABIGradle下载依赖超时没有配置镜像源换国内Maven镜像和Gradle镜像打包后运行时找不到.soABI filters去掉了第三方库的ABI保留第三方库实际包含的ABI4.6 关于“Cocos Creator自带的NDK路径”一点心得Cocos Creator在构建时如果构建面板里的NDK路径留空它会有自己的一套自动探测逻辑先看local.properties里的ndk.dir再查NDK环境变量最后才会报错。所以有些项目别人能打你打不了很可能就是环境变量没设。我在Windows上习惯专门加一个NDK环境变量指向最常用的那个NDK版本目录。这样即使在Cocos和Android Studio里都没手动配置Gradle也有退路可以找到NDK。当然这也引出一个新问题如果你电脑上装了多个NDK版本环境变量只指向一个固定的其他项目指定了别的版本时还是会失效。所以最可靠的还是每个项目都显式在native工程里把ndkVersion指定清楚让项目自带完整的构建说明。4.7 一个真实案例的完整排查过程有个朋友的项目是Cocos Creator 2.4.6突然从旧电脑迁移到新电脑NDK从r21c换成了r26b编译时直接报了一堆“unknown type name”和“use of undeclared identifier”——典型的C编译器跨版本导致的源码兼容问题。我建议他不要在新电脑上做兼容性修补而是直接安装r21e把ndkVersion改成对应版本再重新编译结果一次通过。这个案例说明一个很实用的道理项目锁定的是Cocos Creator版本而不是“最新环境”。迁移开发机、升级Android Studio之后NDK不要跟着SDK最新版走一定要跟着项目模板走。很多人在新电脑上第一件做的事是装最新NDK这本身没错但装完之后一定要记得给项目指定正确版本否则就会出现上面这种“环境越新、项目越挂”的怪象。结尾我在实际打包里踩过最深的坑就是相信了“最新版NDK没问题”这个说法结果一套Cocos Creator 3.6项目在NDK r25c上编译直接崩到怀疑人生。后来养成了固定习惯新建项目先看模板里的preferred NDK version本地没这个版本就针对性装一个装好之后用命令行单独跑一次externalNativeBuild任务验证确认无误再回编辑器打正式包。这套流程看起来绕了远路实际上省下的是反复重试的半天时间。如果你也在配置NDK不妨先按这篇文章里的版本清单对一遍再动手。真遇到本文没覆盖到的报错优先看Cocos构建日志里前五十行NDK相关错误几乎都写在最前面比在社区里翻旧帖快得多。
阅读完成 · 觉得有帮助？
