企业官网建设流程全解析

如果你曾经在 Cocos Creator 里点完构建，看着进度条走完，结果在 Android Studio 那边弹出一行NDK not configured. Download it with SDK manager. Preferred NDK version is ...，那你跟我踩过的是同一个坑。NDK 版本选择与配置这件事，看着只是装个工具链，实际上牵扯到 Cocos 版本、AGP 版本、CMake 版本、ABI 目标，甚至本机 SDK 路径的正反斜杠。这篇文章我想把 Android 打包里关于 NDK 的前因后果一次性说透，包括版本怎么选、装哪个版本、在哪配置、报错怎么排查，都是我在真实项目里试过、炸过、又修好的经验。

先说个结论：NDK 不是越新越好，也不是随便装一个就能用。很多人在这一步卡住，是因为 Cocos 的构建脚本已经在项目里锁定了它期望的 NDK 版本，你本机没装那个版本，或者装了一个不匹配的版本，报错就来了。下面我从打包链路开始拆，把这个配置问题彻底讲清楚。

1. 先弄清楚 NDK 在 Android 打包里的位置，才不会配错方向

1.1 一次 Cocos Android 打包，实际上经历了什么

很多人以为 Cocos Creator 的打包就是 JS/TS 脚本被包进一个壳里，其实不是。Cocos 引擎的底层渲染、物理、音频、资源读取这些核心模块，大部分是用 C++ 写的。你点构建的时候，Cocos 会先生成一个原生 Android 工程，然后由 Gradle 去驱动 CMake 和 NDK，把引擎 C++ 源码交叉编译成.so文件，再和 Java/Kotlin 层、资源一起塞进 APK。

这里的关键点是：NDK 就是给 Android 设备编译 C/C++ 代码的交叉编译工具链。SDK 负责的是 Java 层编译和 APK 打包，NDK 负责 C++ 层。Cocos 这类引擎型的项目，NDK 是刚需，不是可选项。

所以“NDK not configured”这类报错，本质上是构建工程在准备调用 C++ 编译工具链时，发现你本机的环境里没有它认识的 NDK。要么没装，要么装的版本不对，要么路径没指对。

1.2 版本匹配为什么这么严格

Cocos 生成的 Android 原生工程里，其实已经写死了它期望的 NDK 版本。比如你打开工程里的app/build.gradle，经常会看到类似这样的代码：

android { ndkVersion "21.4.7075529" }

这行代码是什么意思？它的意思是：这个工程编译时，请使用版本号为21.4.7075529的 NDK。如果你机器上已经装了 NDK，但装的是25.2.9519653，那 Gradle 不会默默替你换一个版本，而是直接报错。

这是很多新手的困惑来源：明明我装了 NDK，为什么还说我 not configured？因为你装的版本，和工程要求的版本不是同一个。NDK 版本与引擎之间的绑定关系很强，引擎自带的第三方预编译库、CMake 脚本、STL 实现，都是按特定 NDK 行为编写的。换个大版本，轻则工具链参数不兼容，重则编译不过，甚至生成出来的.so在真机上跑不起来。

1.3 配置入口太多，反而容易乱

NDK 相关的配置入口至少有四五个：Cocos Creator 偏好设置里的路径、构建面板里的路径、local.properties文件里的ndk.dir、原生工程里的ndkVersion、还有系统环境变量。热词里出现的一堆ndk配置、local.properties、android sdk官网下载，都跟这些入口有关。

这几个入口不是同一层级的东西。Android Studio 新版已经不再推荐用local.properties里的ndk.dir指定 NDK，而是强烈建议使用 side-by-side 的 NDK 版本目录，配合工程里的ndkVersion字段来锁定版本。Cocos Creator 里的路径设置，主要作用是在生成原生工程时，告诉构建流程去哪个 SDK 下找 NDK。

理解了这个分层关系，后面配置就不会手忙脚乱：生成工程阶段看 Cocos Creator 的路径设置，编译阶段看ndkVersion和本机已安装的 NDK 目录。

提示：NDK 不是你装得越多越好，关键是让项目锁定到它期望的那一版。同一台电脑上装多个版本很正常，重要的是每个项目都能准确找到自己那一份。

2. NDK 版本到底怎么选：先看项目，别先下载

2.1 最权威的版本来源，其实是报错信息

当你拿到一个 Cocos Creator 项目，尤其是别人发给你的、或者从仓库里 clone 下来的工程，第一件事不是打开浏览器搜“Cocos NDK 推荐版本”，而是先看报错和构建脚本。

报错信息里往往直接写着 Gradle 期望的版本。比如开头说的那行：

NDK not configured. Download it with SDK manager. Preferred NDK version is "21.4.7075529".

这里21.4.7075529就是工程锁定的版本。你只需要安装这个精确版本，问题大概率就解决了。

如果工程还没有构建过，没有报错可以参考，那就去原生工程里找：

• app/build.gradle里的ndkVersion
• local.properties里的sdk.dir
• gradle/wrapper/gradle-wrapper.properties里的 Gradle 版本
• build.gradle的 dependencies 里 Android Gradle Plugin 版本

这些信息拼在一起，基本能判断出项目期望的环境。与其网上找一堆“万能配置”，不如把工程自己的配置读明白。

2.2 不同 Cocos Creator 版本的常用 NDK 组合参考

我下面列出来的组合来自我做过的一些项目，以及在社区里看到过的稳定搭配。注意一点：这只是一个参考，不是绝对真理。Cocos 官方文档在不同版本里给出的建议有变化，而且项目里第三库、插件也会影响实际版本需求。

有一个很常见的现象：同一个 Cocos 版本，A 项目用 r21e，B 项目用 r23c，都跑得好好的。这不是玄学，而是因为这两个项目的第三方原生库不一样。只要工程里没有写死ndkVersion，Gradle 会用默认版本，所以看起来好像“什么版本都能用”。但如果另一个项目写死了版本，你机器上没装，立马爆错。

21.4.7075529这个长数字是 Google 的 NDK 版本代号，对应社区常说的 r21e。23.2.8568313对应 r23c。建议你用长数字精确安装，不要只按“r21e”这个名字去猜，因为 NDK 还有个旧版安装目录不带版本号，非常容易搞混。

2.3 不要无脑装最新版 NDK

NDK 从 r23 开始移除了 GCC，r25 以后对最低系统版本、C++ 标准库的支持行为也有变化。如果你的 Cocos 版本比较老，还在用 Android.mk 或者依赖旧版编译链的一些特性，直接上最新 NDK 会出现一堆编译错误，比如找不到libgcc、stlport相关的头文件，或者莫名其妙的链接错误。

我见过一个真实情况：某 2.4.x 项目，开发者装了当时最新的 NDK r26 之后，CMake 阶段一直报clang: error: no such file or directory，排查了很久，最后发现就是 NDK 版本太新，工具链行为变化导致 CMake 配置阶段生成的参数失效。把 NDK 换回 r21e 后一次通过。

注意：遇到编译报错时，如果最近刚升级过 NDK，第一反应应该是“退回项目需要的版本”，而不是去翻 CMake 脚本改参数。除非你有非常明确的升级理由，否则不要动工具链版本。

3. 配置实操全流程：从安装 NDK 到项目跑通

3.1 用 Android Studio 的 SDK Manager 安装指定版本

这是最直观、最不容易出错的方式。前提是你已经装好了 Android Studio，并且至少打开过一次，让它生成了默认 SDK 目录。

操作步骤：

1. 打开 Android Studio，在欢迎页或主界面进入 SDK Manager。
2. 切到 SDK Tools 标签页。
3. 找到 NDK (Side by side)，如果列表里没有，勾选右下角的 Show Package Details。
4. 展开后你会看到一堆版本，找到工程需要的那个精确版本号，比如21.4.7075529。
5. 同时确认 CMake 版本，一般建议装3.22.1，如果工程里指定了其他版本，按需勾选。
6. 点 Apply，等下载安装完成。

安装完成后，NDK 会出现在 SDK 目录的ndk/21.4.7075529文件夹下。这个文件夹里有一个source.properties文件，用来标识 NDK 的版本。

3.2 命令行安装：适合远程开发机和不想开 IDE 的人

如果你懒得开 Android Studio，或者是在一台没有图形界面的构建机上操作，可以直接用sdkmanager命令行安装。

首先要找到sdkmanager的位置。新版 Android SDK 通过cmdline-tools管理，路径一般是：

你的SDK目录/cmdline-tools/latest/bin/sdkmanager

先列出可用的 NDK 版本：

sdkmanager --list | grep ndk

会看到一大堆带版本号的条目，例如：

ndk;21.4.7075529 ndk;23.2.8568313 ndk;25.2.9519653

安装指定版本：

sdkmanager --install "ndk;21.4.7075529" "cmake;3.22.1"

安装结束后，可以用下面命令确认目录存在：

ls 你的SDK目录/ndk/

输出里应该有你刚安装的版本文件夹。如果之前装过其他版本，会并列存在。

3.3 在 Cocos Creator 里把 NDK 路径指对

Cocos Creator 版本不同，设置入口的位置略有差异。

Cocos Creator 3.x：

• 菜单栏打开 偏好设置 -> 外部程序。
• 在 Native 环境分类里，找到 NDK 路径。
• 直接选择你的SDK目录/ndk/21.4.7075529，注意选到具体版本目录，而不是ndk外层目录。
• SDK 路径也同步检查一下，确保指向根目录，比如D:\Android\Sdk。

Cocos Creator 2.x：

• 在构建发布面板中，拉到 Android 配置区。
• 填写 NDK 路径，同样要填到具体版本目录。
• 有些 2.x 版本还支持环境变量方式，设置ANDROID_NDK_ROOT指向 NDK 目录，实测也能生效。

设置完成后，重新构建一次项目。如果这一步没配好，后期打开原生工程时会直接出现找不到 NDK 的提示。

提示：NDK 路径千万别选到旧版那种不带版本号的目录。旧版 NDK 目录结构不同，AGP 在读取source.properties时会失败，报错和你没装 NDK 是一样的。

3.4 用 local.properties 和 ndkVersion 锁住版本

Cocos 构建生成的 Android 工程里，通常会带一个local.properties文件，内容是本地 SDK 路径：

sdk.dir=D\:\\Android\\Sdk

有些老教程会教你在里面加一行：

ndk.dir=D\:\\Android\\Sdk\\ndk\\21.4.7075529

这里要提醒一下：新版 AGP 对这个字段是 deprecated 状态，虽然很多版本还能读，但已经不稳定了。更可靠的锁定方式是在app/build.gradle里显式声明ndkVersion：

android { compileSdkVersion 33 ndkVersion "21.4.7075529" }

这样设置之后，Gradle 会在本机已安装的 side-by-side NDK 里查找精确匹配的版本。如果没找到，会报出我们熟悉的NDK not configured... Preferred NDK version is "21.4.7075529"，看到这个报错就知道缺哪个版本了。

3.5 环境变量的作用有限，但可以辅助定位

老项目里偶尔会用到ANDROID_NDK_HOME或ANDROID_NDK_ROOT环境变量，Cocos 2.x 时代有些构建流程依赖这个。新版 Cocos 和 AGP 的对环境变量的依赖已经很低了，主要看 SDK Manager 安装的 side-by-side 目录。

如果你的构建流程非要环境变量，可以在系统变量里加：

ANDROID_NDK_ROOT=D:\Android\Sdk\ndk\21.4.7075529 ANDROID_SDK_ROOT=D:\Android\Sdk

但要注意：环境变量的优先级比较迷，有时候设置了反而会和工程的ndkVersion打架。我个人的建议是，环境变量作为一种辅助手段，能不动尽量不动，重点把 SDK Manager 安装和工程ndkVersion对齐。

4. 打包阶段的关键参数与一手经验

4.1 ABI 选择和包体大小直接相关

NDK 编译的产物是.so，但 Android 设备有不同的 CPU 架构，也就是 ABI。Cocos 构建面板里一般会让你选择目标平台，常见的四个：

• armeabi-v7a：兼容绝大多数老手机
• arm64-v8a：现在的主流机型
• x86：老模拟器常用
• x86_64：新版模拟器和部分平板

每勾选一个 ABI，NDK 就要完整编译一遍引擎源码，构建时间和最终 APK 体积都会成倍增加。我见过一个项目为了“保险”，四个 ABI 全勾，最终 APK 直接 300 多 MB。实际上现在真机基本都是arm64-v8a，老的armeabi-v7a可以给需要兼容低端机的项目留一个，x86系列只在你经常用模拟器调试时才有必要选。

这里有个常见的反直觉点：如果你的项目依赖了某个第三方原生库，而这个库只提供了armeabi-v7a的.so，那你就不能只勾arm64-v8a，否则真机上会报找不到 so 文件。反过来，只提供arm64-v8a的老库反而很少见。所以 ABI 选择不完全是个人的喜好问题，还得看依赖库给不给面子。

4.2 Gradle 内存配置影响打包稳定性

NDK 编译 C++ 的耗时本来就长，如果你本机内存只有 8GB，还要边开编辑器边打包，Gradle 很容易因为内存不足直接卡死或报 OOM。在原生工程的gradle.properties里，默认可能会有几行配置：

org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m

如果项目比较大，可以适度调高，但要留出系统余量，比如 16GB 内存的机器可以设成：

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m

-Xmx是 Gradle 进程的最大堆内存，并不是设得越大越好。设得比物理内存还大，系统会开始疯狂交换内存，打包速度反而下降。我个人的经验是，最多不超过物理内存的一半，同时尽量关闭其他大内存软件。

4.3 命令行打包和 CI 场景的注意事项

如果你要写脚本批量打渠道包，或者接到 CI 流水线上，就不能依赖 Android Studio 的图形界面了。Cocos Creator 支持命令行构建，常用的参数包括平台、NDK 路径、SDK 路径等。

以 Cocos Creator 3.x 为例，命令行构建大致长这样：

cocos build -p android --ndk-path "D:/Android/Sdk/ndk/21.4.7075529" --sdk-path "D:/Android/Sdk"

不过实际参数会因为版本不同有差异，建议先查一下当前版本的命令行帮助。CI 上最容易忽略的问题是路径格式：Windows 下反斜杠转义经常出问题，建议统一用正斜杠D:/Android/Sdk。

另外，CI 环境里不要依赖 Android Studio 的 SDK Manager 的 GUI 安装，直接用sdkmanager命令装好 NDK 和 CMake，并且把--ndk-path明确传给 Cocos，比靠环境变量要稳得多。

5. 常见报错与排查技巧实录

5.1 经典的“NDK not configured”报错

报错完整版通常是：

NDK not configured. Download it with SDK manager. Preferred NDK version is "21.4.7075529".

排查思路按下面顺序做：

1. 看报错里的 Preferred NDK version 是多少。
2. 打开你的 SDK 目录下的ndk文件夹，看有没有对应版本。
3. 没装就按上面 3.1 或 3.2 的方法装；装了但报错还在，检查 Cocos Creator 里的 NDK 路径是否精确到版本目录。
4. 如果用的是 Android Studio，打开工程后重新 Gradle Sync，让配置生效。

便携老项目还会遇到一种情况：local.properties里sdk.dir指向的是别人机器的旧路径，比如C:\Users\旧用户名\AppData\Local\Android\Sdk。这会直接导致 AGP 找不到整个 SDK，更别说 NDK 了。解决方法是把sdk.dir改成你自己的 SDK 路径，或者直接删除local.properties让 Android Studio 自动生成一份。

5.2 装了新版本 NDK 后编译报错

常见错误有：

Unsupported NDK version requested

或：

A problem occurred configuring project ':app'. > NDK did not have a source.properties file

前者通常是你机器的某个版本不在 AGP 支持范围内，后者是路径指到了旧版 NDK 或者不完整的目录。这两种情况，处理方式都不建议“硬扛”，而是把 NDK 版本切回工程期望的精确版本。

如果项目里没有写死ndkVersion，你可以先看看app/build.gradle里是不是用了ndkVersion，没有的话，Gradle 会用最近安装的版本。如果你之前装过 r25，后来为了兼容其他项目又装了 r21e，Gradle 可能会“偷懒”选到 r25，导致编译错误。解决办法就是显式写上ndkVersion。

5.3 CMake 版本缺失或不对应

Cocos 构建生成的工程一般会依赖 CMake。报错类似于：

CMake '3.22.1' was not found. Install it using SDK manager.

这种处理起来最简单：打开 SDK Manager，在 SDK Tools 里勾选对应的 CMake 版本，或者用命令行：

sdkmanager --install "cmake;3.22.1"

需要注意 CMake 版本和 NDK 版本之间也有兼容关系。高版本 NDK 可能要求 CMake 3.22 以上，老版本 NDK 配太新的 CMake 有时也能跑，但没必要去踩这个边界，按报错提示的版本装就完了。

5.4 路径里的中文和空格坑

Windows 上打包最常见的一类坑就是路径。SDK 路径、NDK 路径、项目路径，任何一个包含中文、空格、特殊符号，CMake 在解析路径时都会出现难以理解的报错。比如D:\游戏项目\release\build这类路径，轻则文件找不到，重则整个构建崩溃。

我现在的习惯是：

• Android SDK 保持在纯英文、无空格的路径，比如D:\Android\Sdk
• NDK 路径由 SDK 目录自动带出，不手动复制到别处
• Cocos 项目路径也用纯英文，比如D:\Projects\MyGame，不用桌面路径

这个习惯帮我避开了非常多查都查不明白的诡异问题。

最后说点个人体会

NDK 版本这件事，看起来是环境配置，但背后是工具链与引擎之间的耦合关系。我踩过最深的坑就是“顺手装了个最新版”，结果整个 C++ 编译阶段持续报错，浪费了一整天。后来学乖了：拿到任何项目，先看报错提示里的 Preferred NDK version，再看工程的ndkVersion，最后才决定装什么。如果你现在正被某个奇怪的 C++ 编译错误折磨，并且最近改过 NDK 版本，我建议你先回到项目原本的版本试试，很多时候问题就是这么简单。工具链保持稳定，比追逐新版本重要得多。