简介：这份资源面向在Mac环境下进行Cocos游戏开发的工程师，聚焦安卓打包环节中ANT工具的完整配置流程，帮助解决从项目编译、签名到生成APK过程中环境搭建与参数调整的实际问题。压缩包共1634个文件，约9.12MB，以1525个html文档为主体，辅以24个pom与24个jar构成ANT运行所需的Java依赖，另有15个xsl样式表、4个cmd与3个bat批处理脚本用于命令行启动，以及xml、properties等配置文件，整体呈现一套可直接落地的ANT工具目录结构。资源围绕ANT安装、环境变量设置、build.xml修改、keystore签名配置、ant release执行及编译优化等关键环节展开，读者可据此对照排查编译错误、资源缺失等常见问题，掌握打包参数调整与混淆开关设置，提升安卓应用的发布效率与质量。目前已有441人学习下载，适合具备一定Cocos基础、需要系统补齐安卓打包技能的中级开发者参考。
1. 从一次构建失败说起：Cocos 安卓打包为什么绕不开 ANT
上周帮一位做休闲游戏的朋友排查构建问题，他的 Cocos Creator 项目在编辑器里跑得好好的，一点「构建 Android」就报BUILD FAILED，日志翻到最底下写着Unable to locate a Java Runtime和sdk.dir is missing。他以为换个打包插件就能解决，折腾两天没进展。其实这类问题九成出在 ANT 这套老构建链的环境配置上——Cocos 的安卓原生构建底层依赖 ANT 来驱动 SDK、NDK、JDK 的协同工作，只要其中一环路径没对上，构建就直接翻车。
这份「Cocos 安卓打包 ANT 全套配置」资源，本质是把 JDK、SDK、NDK、ANT 四件套的版本匹配、环境变量、路径指向和常见报错一次性整理清楚，让你不用在论坛里东拼西凑。它适合两类人：一是刚接触 Cocos 安卓原生构建、被环境变量劝退的新手；二是换了机器或升级引擎后构建突然失败、需要快速定位的老手。下面我按「先搞懂这套链在干什么，再动手配，最后避坑」的顺序拆开讲。
2. ANT 构建链的四个组件：版本匹配与目录规划
2.1 为什么 Cocos 安卓构建还在用 ANT
很多人第一反应是「都什么年代了还用 ANT，Gradle 不香吗」。这里要说清楚：Cocos Creator 在构建安卓原生工程时，早期版本（尤其是 2.x 系列）默认走的就是 ANT 脚本，build.xml、local.properties、project.properties这套文件结构是 ANT 的典型特征。即便后来部分版本支持 Gradle，ANT 依然是底层编译流程的默认驱动之一，尤其是涉及android update project生成工程、ant release打签名包这些环节。
ANT 的好处是轻、直接、依赖少，一个build.xml就能描述整个编译流程；坏处是它不帮你管理依赖版本，JDK、SDK、NDK 的路径和版本全靠你手动对齐。所以「全套配置」的核心不是装软件，而是让四个组件的版本和路径互相认得对方。
2.2 四件套的版本对应关系
先看一张我整理的版本匹配表，这是踩了无数次坑之后总结出来的：
| 组件 | 推荐版本 | 作用 | 不匹配的典型症状 |
|---|---|---|---|
| JDK | 1.8（8u 系列） | 编译 Java 层代码 | 高版本 JDK 报Unsupported class file major version |
| Android SDK | API 28 及以下 | 提供 android.jar 和构建工具 | 高 API 缺dx工具，ANT 找不到 |
| NDK | r10e ~ r19c | 编译 C++ 原生层 | 高版本 NDK 移除gnustl，链接报错 |
| ANT | 1.9.x | 驱动整个构建流程 | 1.10 在某些脚本下报 task 找不到 |
这张表的关键信息是：不要盲目追新。Cocos 的 ANT 构建链对高版本 JDK 和 NDK 兼容性很差，JDK 用 1.8、NDK 控制在 r19c 以下，能省掉一大半玄学问题。我一般会把 JDK 和 NDK 都放在一个独立的devtools目录下，不跟系统默认环境混在一起，方便随时切换。
2.3 目录规划：把路径固定下来
在动手配环境变量之前，先把目录结构定好。我习惯这样组织：
# 建议的目录结构（Windows 示例，macOS/Linux 换成对应路径） D:/devtools/ ├── jdk1.8.0_291/ # JDK 解压目录 ├── android-sdk/ # SDK 根目录 │ ├── tools/ # 含 ant 相关脚本 │ ├── platform-tools/ # adb 等 │ ├── build-tools/ # 各版本构建工具 │ └── platforms/ # android-XX 平台 ├── android-ndk-r19c/ # NDK 解压目录 └── apache-ant-1.9.16/ # ANT 解压目录这样规划的好处是：所有路径都是确定的、可预测的，后面配local.properties和环境变量时直接拼路径就行，不用去系统里到处找。注意 SDK 和 NDK 的目录名不要带空格和中文，ANT 脚本对空格路径的处理很脆弱，这是血泪经验。
3. 环境变量与 local.properties：让构建脚本找到工具
3.1 环境变量的正确配法
环境变量是 ANT 构建链的「导航系统」，配错一个，构建就找不到北。需要配的有四个：
# JAVA_HOME 指向 JDK 根目录，不是 bin 目录 JAVA_HOME = D:/devtools/jdk1.8.0_291 # ANDROID_HOME 指向 SDK 根目录 ANDROID_HOME = D:/devtools/android-sdk # ANT_HOME 指向 ANT 根目录 ANT_HOME = D:/devtools/apache-ant-1.9.16 # NDK_HOME（部分 Cocos 版本需要）指向 NDK 根目录 NDK_HOME = D:/devtools/android-ndk-r19c # PATH 里追加各工具的 bin 目录 PATH = %JAVA_HOME%/bin;%ANDROID_HOME%/tools;%ANDROID_HOME%/platform-tools;%ANT_HOME%/bin;%PATH%配完之后一定要开一个新的命令行窗口验证，因为环境变量只在窗口启动时读取一次：
java -version # 应输出 1.8.x ant -version # 应输出 Apache Ant(TM) version 1.9.x adb version # 应输出 Android Debug Bridge version如果java -version输出的还是系统里另一个高版本 JDK，说明 PATH 里旧路径排在前面，把%JAVA_HOME%/bin挪到最前面即可。这个顺序问题非常隐蔽，很多人配了 JAVA_HOME 却依然报版本错误，就是 PATH 顺序没调。
3.2 local.properties：工程级的路径声明
环境变量是全局的，但 Cocos 构建出的安卓工程里还有一个local.properties文件，它才是 ANT 真正读取 SDK 路径的地方。这个文件在构建目录的frameworks/runtime-src/proj.android/下，内容很简单：
# local.properties —— ANT 构建时读取的 SDK/NDK 路径 sdk.dir=D:\\devtools\\android-sdk ndk.dir=D:\\devtools\\android-ndk-r19c两个注意点：一是 Windows 下路径的反斜杠要写成双反斜杠\\，或者直接用正斜杠/，单反斜杠会被当成转义字符；二是这个文件有时会被构建流程覆盖或删除，如果构建报sdk.dir is missing，先检查它还在不在。我一般会把它备份一份，构建失败时直接覆盖回去。
3.3 用命令行验证整条链是否打通
环境配好后，别急着在编辑器里点构建，先用命令行手动跑一遍，这样报错信息最完整：
# 进入安卓工程目录 cd your-project/frameworks/runtime-src/proj.android # 先清理旧构建产物 ant clean # 执行 debug 构建 ant debugant debug会依次调用 SDK 的aapt、dx、apkbuilder等工具，任何一环路径不对都会在这里暴露。如果输出BUILD SUCCESSFUL，说明整条链打通了，再去编辑器里构建基本不会出问题。如果失败，日志里会明确告诉你哪个工具没找到，按提示回去补路径即可。
4. 避坑与排查：构建失败时先看这五条
4.1 报错Unable to locate a Java Runtime
现象：命令行执行ant debug直接报找不到 Java 运行时，或者编辑器构建日志里出现这行。原因：JAVA_HOME 没配、配错，或者 PATH 里 JDK 的 bin 目录没加进去。还有一种情况是装了多个 JDK，系统默认指向了高版本。解决：echo %JAVA_HOME%确认路径存在且指向 JDK 根目录；where java看实际调用的是哪个 java.exe，如果是系统目录下的，说明 PATH 顺序有问题，把%JAVA_HOME%/bin提到最前。
4.2 报错sdk.dir is missing
现象：构建到一半提示sdk.dir is missing. Make sure to generate local.properties。原因：local.properties文件不存在，或者里面的sdk.dir路径写错、路径里有空格。解决：手动在proj.android目录下创建local.properties，写入正确的sdk.dir。路径用正斜杠或双反斜杠，绝对不要有空格和中文。如果文件存在还报错，检查是不是被构建流程覆盖成了空文件。
4.3 NDK 版本过高导致链接失败
现象：Java 层编译通过，但 C++ 原生层链接时报undefined reference to或找不到gnustl_static。原因：NDK r20 及以上版本移除了gnustl运行时库，而 Cocos 老版本的Android.mk里还在引用它。解决：换回 r19c 或更低版本的 NDK。如果必须用高版本，需要手动改Android.mk里的LOCAL_STATIC_LIBRARIES，把gnustl_static换成c++_static，但这涉及原生层代码改动，风险较大，新手不建议。
4.4 ANT 报taskdef class ... cannot be found
现象：执行ant debug时报某个 task 类找不到，比如taskdef class com.android.ant.SetupTask cannot be found。原因：ANT 版本过高（1.10+）或者 SDK 的tools/lib/anttasks.jar没被正确加载。解决：降级到 ANT 1.9.x。同时确认ANDROID_HOME/tools/lib/下有anttasks.jar、sdklib.jar等文件，这些是 ANT 调用 SDK 功能的桥梁，缺了就会报 task 找不到。
4.5 构建成功但安装后闪退
现象：ant debug显示BUILD SUCCESSFUL，APK 也装上了，但一打开就闪退。原因：多半是原生库没打进去，或者 ABI 架构不匹配。比如只编了armeabi-v7a，但设备是arm64-v8a。解决：检查proj.android/libs/下有没有对应的.so文件，Application.mk里的APP_ABI是否覆盖了目标设备架构。用adb logcat看闪退时的 native crash 日志，能直接定位到缺哪个库。
5. 进阶技巧：用脚本固化配置，换机器不再重配
配一次环境不难，难的是换机器、换引擎版本、团队协作时每次都要重来。我的做法是把整套配置写成一个初始化脚本，新机器上跑一遍就完事。下面是一个 Windows 批处理示例，macOS/Linux 换成 shell 脚本即可：
@echo off REM init_android_env.bat —— 一键初始化 Cocos 安卓构建环境 set DEVTOOLS=D:\devtools REM 设置环境变量（仅当前会话有效，避免污染系统） set JAVA_HOME=%DEVTOOLS%\jdk1.8.0_291 set ANDROID_HOME=%DEVTOOLS%\android-sdk set ANT_HOME=%DEVTOOLS%\apache-ant-1.9.16 set NDK_HOME=%DEVTOOLS%\android-ndk-r19c set PATH=%JAVA_HOME%\bin;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools;%ANT_HOME%\bin;%PATH% REM 验证关键工具 echo === 环境验证 === java -version ant -version adb version REM 写入 local.properties（假设工程在当前目录的 proj.android 下） set PROJ=%~dp0proj.android if exist "%PROJ%" ( echo sdk.dir=%ANDROID_HOME:\=/%> "%PROJ%\local.properties" echo ndk.dir=%NDK_HOME:\=/%>> "%PROJ%\local.properties" echo local.properties 已写入 ) else ( echo 未找到 proj.android 目录，请检查路径 )这个脚本做了三件事：设置当前会话的环境变量（不污染系统全局）、验证工具是否可用、自动生成local.properties。注意%ANDROID_HOME:\=/%这个写法是把反斜杠替换成正斜杠，因为local.properties里用正斜杠更稳妥。
再补一个验证方法：构建出 APK 后，用aapt dump badging检查包信息，确认版本号、ABI、权限都符合预期：
# 查看 APK 的包名、版本、支持的 ABI aapt dump badging your-app-debug.apk | findstr "package native-code"输出里native-code那一行会列出打进包里的 ABI 架构，如果只有armeabi-v7a而你的测试机是 64 位，就该回去改Application.mk了。
从那以后我每次换机器或升级引擎，都强制先跑一遍这个初始化脚本，再执行ant clean && ant debug，确认命令行能构建成功之后才打开编辑器。这套习惯帮我省掉了至少十次「编辑器构建失败但不知道从哪查」的折腾。希望帮到你。
本文还有配套的精品资源，点击获取
