简介面向 Cocos 游戏开发者的安卓打包配置资料聚焦 Mac 环境下借助 ANT 工具完成项目编译、APK 生成与签名发布的完整流程涵盖从环境搭建、构建脚本调整到应用市场上线的全链路适合需要将游戏快速部署到 Android 终端的开发与构建人员。包体共 1634 个文件以 HTML 参考文档、JAR 运行依赖、POM/XML 构建配置以及 BAT/CMD 辅助脚本为主压缩包仅 9.12MB文件类型清晰便于按需检索。已有 439 人学习下载。资源围绕 ANT 安装与环境变量设置、build.xml 核心参数调整、keystore 签名信息配置、ant release 执行及常见错误排查展开并具体给出 keytool 生成签名文件、混淆开关优化等细节内容预览中可见 ant、antRun 等关键入口可帮助读者直接对照真实目录结构按步骤复现打包流程提升安卓构建效率减少发布前的试错成本。1. Cocos安卓打包ANT全套配置老项目为什么绕不开它当新同事一上来就想把老 Cocos 工程换成 Gradle 构建时最省成本的路径通常是先把 ANT 全套配置补齐。所谓 Cocos 安卓打包 ANT 全套配置就是把 JDK、NDK、Android SDK、Ant 四件套的环境和版本对齐再配好 build.xml、ant.properties、project.properties 与 JNI 构建文件让一条 ant release 命令能从 C 源码一路产出签名 APK。它适合正在维护老版本 Cocos、需要按渠道批量出包、或在 CI 上保留旧流水线的团队。下面按我实际排障的顺序把这套配置从原理拆到参数再落到坑上。2. ANT打包四件套JDK、NDK、SDK、Ant 的版本匹配与验证2.1 ANT 在这条打包链路里到底做了什么APK 本质上是多语言产物C 引擎源码要编成 .soJava 壳要编成 .class 再转成 .dex资源要交给 aapt 打包并生成 R.java最后还要签名和对齐。ANT 本身不做任何编译它只负责按 target 依赖关系把外部工具串起来。Cocos 老工程里ANT 的标准触发链大致是-setup 读 SDK 路径与 target-compile 用 javac 编译 Java 壳与引擎 Java 库-dex 用 dx/d8 转 classes.dex-package 由 aapt 连同 so、资源、assets 组包-sign 签名-zipalign 做对齐。这条链里最容易看错的一点是 ANT 的每个任务本质都在 PATH 里找可执行文件javac 找不到报在编译阶段dx 找不到报在 dex 阶段aapt 找不到报在资源阶段。所以很多打包翻车根本不是脚本写错而是工具链没进 PATH。Cocos 老框架里引擎 C 部分由 ndk-build 根据 jni/Android.mk 和 jni/Application.mk 编译Java 壳在 proj.android/src 下两部分谁先编都行但进入 -package 前必须确认 jni/../libs/armeabi-v7a/libcocos2d*.so 已经存在ANT 不会像 Gradle 模板那样自动替你编 C。这也是老工程打包教程里总让你先跑 build_native.py 再跑 ant 的原因。ANT 不聪明但它每一步都直白错误发生的位置几乎等于问题所在的环节这是它比黑盒脚本强的地方。老 Cocos 默认采用 ANT是因为它直接继承了 ADT 时代的构建体系模板轻、脚本透明、错误定位容易。很多团队不是不想升级构建方式而是引擎模板动一处就要回归一轮ANT 只要环境齐全出包行为多年不变。正是这个原因我推荐先补全配置而不是重写 Gradle后面你会看到整套配置其实只有几个文件。2.2 版本匹配最容易翻车的地方不是脚本而是工具链ANT 老配置对版本敏感我一般锁在下面这套组合上组件经验常用版本版本偏高时的表现备注JDKJDK 8dx 报 class file version 51.0 不支持ANT 任务在 JDK 9 上偶发工具兼容问题构建机默认 JDK 别设成 11/17Android SDKplatform-tools 保持最新build-tools 28.0.3build-tools 31 移除 dxANT 规则直接失败28.0.3 是 ANT 场景常用版本NDKr16br17 起移除 gcc老 Android.mk 报 Unknown or unsupported toolchain老工程锁 r16b 最省事Apache Ant1.9.141.10 对 Java 版本要求变化部分老可选任务缺失版本换高没有任何收益老工程常用 NDK r1xAndroid.mk 里那句NDK_TOOLCHAIN_VERSION : 4.9在 r17 之后会直接失效。装 NDK 时别把所有版本都塞进 PATH构建机上只暴露当前工程要用的那一个。我踩过最重的坑是机器上装了三个 NDKndk-build 用的是另一个版本编出的 so 在低端机上启动崩溃查了一天最后发现是路径优先级问题。SDK 部分还有个隐藏前提ANT 规则依赖sdk/tools/ant/build.xml和 build-tools 里的 aapt、dx。新装的 SDK 往往只剩 cmdline-toolstools/ant 目录已经不存在遇到这种情况从老机器把整个sdk/tools/ant目录拷过来即可规则文件不挑版本。2.3 三行命令确认四件套就绪先给环境变量模板这段是整套配置的地基export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export ANDROID_SDK_ROOT$HOME/Android/Sdk export ANDROID_NDK_ROOT$HOME/android-ndk-r16b export ANT_HOME/opt/apache-ant-1.9.14 export PATH$JAVA_HOME/bin:$ANT_HOME/bin:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_NDK_ROOT:$PATHJAVA_HOME 决定 javac 来源ANDROID_SDK_ROOT 供 build_native.py 与后续脚本识别 SDKANDROID_NDK_ROOT 是 Cocos 老脚本读取 NDK 的固定变量名ANT_HOME 只管 ant 命令。PATH 里把 JAVA_HOME/bin 放最前避免系统自带的另一个 java 抢先。验证命令用四条短命令java -version 21 | head -n 1 ant -version 21 | head -n 1 adb version 21 | head -n 1 ndk-build --version 21 | tail -n 1如果 java -version 显示的不是 1.8先回头改 JAVA_HOME如果 ant -version 显示 1.10建议换回 1.9后面会讲原因。adb version 输出里能看到 Android Debug Bridge 和 SDK 路径这是确认 platform-tools 进 PATH 的好方法。ndk-build --version 在老版本 NDK 下打印的是 GNU Make 3.81看到这个数字不代表编译错了反而说明 NDK 可用。四条命令都正常后才进入工程配置否则先解决环境再看 build.xml能少走一半弯路。3. ANT全套配置落地build.xml、ant.properties 与最小出包命令3.1 一个老 Cocos 工程里ANT 全套配置包含哪些文件先把文件清单摆出来后续所有操作围绕它们文件位置作用build.xmlproj.android/ANT 入口定义工程名并引用 SDK 规则project.propertiesproj.android/声明 target 与 Android library 引用ant.propertiesproj.android/工程名、入口 Activity、签名参数local.propertiesproj.android/可选声明 sdk.dir每台机器可不同jni/Android.mkproj.android/jni/C 模块编译规则jni/Application.mkproj.android/jni/ABI、STL、工具链版本build_native.py工程根目录可选调 ndk-build 编 so 的封装脚本这七类文件里真正需要你动手改的往往只有 ant.properties、project.properties 和 build.xml。Android.mk 和 Application.mk 通常跟着引擎模板走不换 NDK 大版本就很少动。local.properties 我一般建议保留它的作用是让每个构建机写自己的 SDK 路径不污染仓库里的公共配置。3.2 build.xml 模板逐行拆解一个典型的老 Cocos build.xml 就十几行核心是把 SDK 的构建规则引进来?xml version1.0 encodingUTF-8? project nameGameDemo defaulthelp !-- 1. 按顺序加载属性文件 -- loadproperties srcFilelocal.properties / loadproperties srcFileant.properties / loadproperties srcFileproject.properties / !-- 2. 校验 sdk.dir 必须存在 -- fail messagesdk.dir is missing. 请在 local.properties 或 ant.properties 中设置 sdk.dir condition not isset propertysdk.dir / /not /condition /fail !-- 3. 引用 SDK 内置构建规则debug/release 全由它提供 -- import file${sdk.dir}/tools/ant/build.xml / /project这里有个容易误解的点loadproperties 按顺序读取但 Ant 属性一旦设置在一个项目里就不能再变所以排在前面的 local.properties 先到先得。每台构建机把自己的 sdk.dir 写进 local.properties团队公共配置放 ant.properties两者不冲突。fail 加 condition 是最实用的开关新手环境最容易缺 sdk.dir与其等 import 后报一堆堆栈不如在这里一句话点破。import 那句是整个文件的灵魂SDK 的 android_rules 全部由它引入ant debug、ant release 这些标准命令都是 import 进来的。3.3 ant.properties 与 project.properties 参数对照ant.properties 长这样# ant.properties sdk.dir/opt/android-sdk targetandroid-21 app.nameGameDemo android.entryorg.cocos2dx.cpp.AppActivity # release 签名四项缺一不可 key.storerelease.keystore key.aliasgame key.store.password****** key.alias.password******project.properties 至少要有targetandroid-21 android.library.reference../cocos/platform/android/javatarget 决定编译用哪个平台版本的 android.jarandroid-21 表示 API 21它必须对应 SDK 里已经安装的 platform否则第 5 章第一个坑就会出现。注意 target 和 AndroidManifest.xml 里的 minSdk、targetSdk 是两个概念前者管编译期后者管运行期行为。android.library.reference 指向引擎自带的 Java 库工程老工程常因为路径配错在 R 类生成和资源合并阶段报重复资源。android.entry 是主 Activity 全限定名部分脚本和加固工具会读取它来定位启动项写错会导致打包成功但桌面图标点击闪退。3.4 工程缺少 build.xml 时的补救方法从仓库拉下来的工程只有 proj.android 目录、没有 build.xml 的情况很常见。常见做法是找同 Cocos 版本的老工程复制模板改工程名就够了# 从模板工程复制 build.xml并替换工程名 cp /work/templates/build.xml proj.android/build.xml sed -i s/name[^]*/nameGameDemo/ proj.android/build.xml # 补一份本机 local.properties避免改公共配置 printf sdk.dir/opt/android-sdk\n proj.android/local.propertiessed 的正则只替换 project 标签里的 name 属性如果用老模板里的名字带空格或点号替换后要检查一遍。补完 build.xml 的第一件事不是直接打包而是跑ant help5 秒内就能判断模板是否解析成功。如果报 sdk.dir 缺失说明 local.properties 没被读进去先看文件位置是不是在 proj.android 根目录。3.5 打 debug 包的最小命令环境就绪、文件配齐后的最小流程只有三步cd /work/GameDemo/proj.android ant clean ant debug ls -lh bin/*.apkant clean 必须做ANT 不会像 Gradle 那样维护增量状态老产物残留会导致 R.java、资源 ID 对不上的诡异问题。跑完后 bin 目录生成 GameDemo-debug.apk。debug 包默认使用 ~/.android/debug.keystore 自动签名ant.properties 里不配签名也能出包。CI 容器里 HOME 每次不同会导致 debug.keystore 重新生成最好用-Ddebug.key.store/fixed/path/debug.keystore固定路径。如果 APK 没生成看控制台第一个 ERROR 出现在哪个阶段-compile 阶段报 javac-dex 阶段报 dx-package 阶段报 aapt阶段名本身就指明了排查方向。注意ANT 不会自动编译引擎 C 源码进入打包前先确认 proj.android/libs 下对应 ABI 的 .so 已生成否则会打出没有 so 的空包安装后启动即崩。4. 正式出包签名、对齐、多渠道打包4.1 用 keytool 生成正式签名并写进 ant.properties正式包必须有自己的签名用 keytool 生成并配置到 ant.propertieskeytool -genkey -v -keystore release.keystore \ -alias game -keyalg RSA -keysize 2048 -validity 36500 \ -dname CNGameDemo,OSomeStudio,CCN-keygen 参数里 -validity 36500 是证书有效天数100 年避免应用在维护期突然证书过期导致无法覆盖安装。-keysize 2048 是通用选择兼容所有老设备。RSA 密钥长度越大并不代表安卓设备越认4096 在某些低端设备上有解析问题。-dname 一次性写入证书信息避免交互式提问在 CI 上卡住DN 里的内容写入后就改不了。生成后把 key.store、key.alias、两个密码写进 ant.properties 的 release 区段注意密钥文件千万别提交进代码仓库团队里我习惯放在构建机独立目录.gitignore 里直接忽略 *.keystore。4.2 release 打包与 zipalign 对齐验证ant release 的产物在 bin/GameDemo-release.apk但不要只看文件存在就认为成功。老 SDK 的 ANT 规则默认在签名后调用 zipalign是否真对齐要靠命令验证zipalign -c -v 4 bin/GameDemo-release.apk apksigner verify --print-certs bin/GameDemo-release.apkzipalign 的 -c 表示只检查不对齐-v 输出详细日志4 是 4 字节对齐。安卓通用市场只要求 4 字节对齐近年部分应用市场开始要求原生库 16KB 对齐那需要更高版本的构建工具支持ANT 老规则最多做到 4 字节如果目标市场明确要求 16KB就得迁移到 Gradle 或者额外处理。apksigner verify 输出能看到证书指纹和签名算法它只显示Verified using v1 scheme时说明用的是老签名方案新系统安装时对旧 v1 签名的兼容在收紧老包上架前最好用 apksigner 重新签一遍让包带上 v2 及以上方案。4.3 混淆配置别误伤 JNI 接口与反射入口release 默认会开混淆但 Java 层被混淆后C 侧通过 JNI 按方法名找 Java 方法会找不到。project.properties 里加上proguard.config${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txtproguard-project.txt 最基础的三条规则-keep class org.cocos2dx.** { *; } -keepclasseswithmembernames class * { native methods; } -keepclasseswithmembers class * { void setTargetSdkVersion(***); }规则一保住 Cocos 引擎的 Java 包规则二保住所有 native 方法名不被改规则三保住通过反射调用的方法。这里没有万能规则每次给 C 新增 Java 层接口都要回来确认方法是否命中 keep 规则否则运行时报 NoSuchMethodError 极难排查。4.4 批量渠道包用属性参数而不是改代码老渠道包的常见做法是往 assets 里写渠道文件比改 AndroidManifest 里的 meta-data 更不容易被加固工具搞丢。批量出包直接用一个 for 循环for ch in huawei xiaomi oppo vivo; do echo $ch assets/channel.txt ant clean /dev/null 21 ant release -Dchannel$ch logs/build_${ch}.log 21 if zipalign -c 4 bin/GameDemo-release.apk; then cp bin/GameDemo-release.apk dist/GameDemo_${ch}_$(date %Y%m%d).apk else echo $ch build failed, see logs/build_${ch}.log fi done-Dchannel$ch 是 Ant 里最顺手的参数注入方式build.xml 里用 ${channel} 读取。命令行 -D 定义的属性优先级高于 properties 文件所以不要在 ant.properties 里定义同名属性否则容易混乱。每次循环前 ant clean 很关键否则 assets 里上次的渠道号可能被残留缓存带进包。日志单独存文件失败时不打断脚本批量出 10 个渠道只需盯失败日志的尾巴。5. ANT打包避坑手册五个高频问题与定位路径下面五条是按实际出包频率排序的每一条我都付过时间成本你按现象对照处理能省不少功夫。5.1 Unable to resolve project target android-21现象ant debug 刚跑出几行就退出报Unable to resolve project target android-21有时后面还跟着一串resource not found。原因project.properties 里 target 写的是 android-21但本机 SDK 没安装 Android 5.0 对应 platformANT 找不到 android.jar。解决优先补装平台而不是改 target。构建机装了 cmdline-tools 时可以直接$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager platforms;android-21没有 cmdline-tools 就用 SDK Manager 图形界面勾选对应平台。改 target 会改变编译期 API 行为老项目一改容易带出新问题。我一般优先装 platform保证工程文件原样不动。5.2 dx 阶段报 Java heap space现象打包进度停在 -dex 阶段报java.lang.OutOfMemoryError: Java heap space有时是GC overhead limit exceeded。原因Ant 调 dx 的 Java 进程默认堆太小工程引用多个 library 后 dex 阶段内存需求上涨。解决给 ANT 的 Java 任务加大堆内存export ANT_OPTS-Xmx1024m ant debugWindows 下对应set ANT_OPTS-Xmx1024m。ANT_OPTS 要写在 ant 命令之前写在 ant.properties 里不生效。如果项目方法数逼近 65K再通过构建规则里的 dex.extra.flags 传入 --multi-dex 开启分包但这只是缓解方法数长期超限还是得拆工程。5.3 ndk-build 报 Unknown or unsupported toolchain现象编译 C 时输出Unknown or unsupported toolchain [gcc]或/bin/sh: gcc: command not found。原因NDK r17 起移除 GCC老工程 Android.mk 里的NDK_TOOLCHAIN_VERSION : 4.9变成无效配置。解决最省事的是锁 NDK r16b重新设置 ANDROID_NDK_ROOT 后重跑 ndk-build。坚持用新 NDK 就要删掉 Android.mk 里的工具链版本行、切 clang同时处理引擎源码里的兼容性问题工作量按天算。我习惯在项目根目录 README 里写死 NDK 目录名并且在构建脚本第一行打印 ndk-build 的路径防止团队里有人装错版本还浑然不觉。5.4 release 包安装报 INSTALL_PARSE_FAILED_NO_CERTIFICATES现象APK 有几十 MB传到手机安装却提示无证书或解析失败。原因release 任务没读到签名配置。常见子因是 ant.properties 里 key.store 写相对路径而当前工作目录不在 proj.android或者四项签名参数里少了 alias。解决先定位再重打cd /work/GameDemo/proj.android ant clean release apksigner verify --print-certs bin/GameDemo-release.apkverify 报DOES NOT VERIFY时基本可以判断未签名或签名参数没读到。把 key.store 改成绝对路径重新 ant clean release 再验证一次。签名问题十次有八次是这种看似玄学的路径问题先查工作目录再查属性项比反复换 keystore 更有效。5.5 build_native.py 报 SyntaxError: invalid syntax现象跑 Cocos 老工程的 build_native.py第一行就报 Python 语法错误。原因老 Cocos 的构建脚本是 Python 2 写的机器默认 python 是 3.xprint 语法差异第一个翻车。解决装 Python 2 并显式调用python2 build_native.py或者绕开脚本直接调 ndk-build$ANDROID_NDK_ROOT/ndk-build -C proj.android \ NDK_PROJECT_PATHproj.android NDK_APPLICATION_MKproj.android/jni/Application.mk \ -j4这样绕过了脚本层的 Python 版本问题同时引擎编译参数不变。CI 里我还会把python --version作为第一条日志输出下次出问题先看它几秒钟就能排除方向。6. 把ANT配置沉淀成一条可复用的出包命令到这里配置的细节都讲完了最后给一条能直接放进 CI 的壳。核心思想是让环境变量、密钥、日志路径完全在脚本里固化人只负责传渠道参数#!/usr/bin/env bash set -euo pipefail export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export ANDROID_SDK_ROOT/opt/android-sdk export ANDROID_NDK_ROOT/opt/android-ndk-r16b export ANT_HOME/opt/apache-ant-1.9.14 export PATH$JAVA_HOME/bin:$ANT_HOME/bin:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_NDK_ROOT:$PATH source /opt/build-secrets/keys.env cd /srv/gamedemo/proj.android ant clean /dev/null 21 $ANDROID_NDK_ROOT/ndk-build -j4 /dev/null 21 ant release /dev/null 21 zipalign -c 4 bin/GameDemo-release.apkset -euo pipefail 让任何一步失败立刻退出并带非 0 状态CI 才能准确拦截。密钥和签名密码不写进仓库由 keys.env 提供。这条脚本看起来简单但它把第 2 章的环境变量、第 3 章的构建链路、第 4 章的对齐验收全部串起来了。我的习惯是每次改完构建相关文件先跑一次 ant clean 加 ant debug 当冒烟再决定要不要开 release。ANT 这套东西一旦版本对齐行为非常可预期它最大的成本在环境维护而不在脚本本身。把这个环境用法写进项目文档新同事接手时照着跑一遍四件套验证命令基本不会再踩第 5 章那些坑。希望帮到你。本文还有配套的精品资源点击获取