Cocos安卓ANT打包全链路：版本对齐、签名与排错-北京尧图网络

简介这份 Cocos 安卓打包 ANT 全套配置资料面向在 Mac 环境下使用 Cocos 开发、需要将游戏工程编译并签名成 Android APK 的开发者重点解决 ANT 工具安装、环境变量设置、构建脚本调整、签名配置及 release 打包中的常见问题也可作为熟悉跨平台发布流程的参考。压缩包共 1634 个文件约 9.12MB以 1525 个 html 文档和 24 个 jar、24 个 pom 为主并含 xsl、xml、properties 及 cmd/bat 脚本等既保留工具链说明与依赖组件也提供可执行的构建文件。已有 441 人学习适合初次接触 Cocos 安卓打包或需要补齐 ANT 配置细节的读者。资料可帮助查阅安装目录与 PATH 设置、build.xml 参数调整、keystore 签名写法、ant release 执行流程和构建报错定位并借助文档与脚本理解编译、签名、优化之间的衔接逐步形成较完整的打包配置思路。对需要复现 Mac 下完整打包链路、减少环境配置反复试错的人较有参考价值。1. 三个「最新」版本换来一次打包失败ANT 链路先对齐再动手有同学把一份 Cocos 项目发过来说安卓打包卡在UnsupportedClassVersionError已经三天环境变量截图一发JDK 17、SDK 34、ANT 1.10全是新的。问题恰恰出在「全是最新」这四个字上ANT 这条链路是 Cocos2d-x 3.x 到 Cocos Creator 1.x、2.x 前中期的主力构建方式它认的是 JDK 8、Android SDK Platform 老版本、NDK r10 到 r17 这一代工具。版本一旦错位配置文件写得再全也只是摆设。这篇内容不讲软件怎么下载安装而是把版本、路径、签名参数一次性配到能复现的程度适合还在维护老工程、或者要在不装 Android Studio 的构建机上出包的从业者。2. 拆开 proj.androidANT 构建链路里到底有哪些文件在干活2.1 ANT 与 gradle 的分工边界先搞清再谈配置Cocos Creator 从 2.4 开始构建面板底层切的已经是 gradleproj.android目录里出现的是build.gradle、gradle.properties、settings.gradle而 1.x 和 2.02.3 生成的工程里躺着的是build.xml、local.properties、project.properties、ant.properties。这两套东西不是换个命令就能互通的判断标准很简单目录里有build.xml且内容是一段import file${sdk.dir}/tools/ant/build.xml /那走的就是 ANT。ANT 相比 gradle 少了什么少了依赖仓库、少了插件生态、少了增量任务图它本质是「按 build.xml 里的 target 顺序执行一串 exec 任务」。所以它有两个很实在的好处构建机不需要联网拉依赖一台 2C4G 的机器就能跑构建链路短从clean到出 apk 往往一两分钟。代价也很明显SDK Tools 26 之后官方移除了tools/ant/build.xml这个模板文件新版 SDK 里根本找不到它这就是很多人换了新 SDK 之后 ant 直接报「build.xml 不存在」的根因。我的建议是选型只看一件事——工程里还有没有jni/Android.mk。有说明 native 层走的是 ndk-build那 ANT 这套是原配没有、纯 Java 插件工程那早点迁 gradle别在 ANT 上耗。2.2 六个文件决定构建成败proj.android下文件不少真正影响出包的就六个其余是资源和源码。把这六个文件的作用和改动频率列清楚出问题时能快速定位该看哪个。文件作用改动频率出错后的典型表现build.xml引入 SDK 的 ant 构建模板定义 clean/debug/release 目标基本不动提示找不到tools/ant/build.xmllocal.properties声明sdk.dir与ndk.dir绝对路径换机器才改sdk.dir is missingproject.properties声明编译目标targetandroid-XX与库工程引用换 SDK 时改Unable to resolve targetant.properties四个签名键release 包必填换签名才改产出-unsigned.apkjni/Application.mkABI、STL、平台版本按渠道/包体积调so 缺失或体积翻倍AndroidManifest.xml包名、versionCode、权限、Activity每次发版改覆盖安装失败、渠道串错这里有个容易忽略的点project.properties里的android.library.reference.1指向引擎的 Java 库工程路径是相对proj.android的。工程被拷到别处、或者引擎目录改了名这个相对路径就断了报错信息往往是一句含糊的「Library project not found」不会告诉你具体是哪个引用。2.3 local.properties 与 project.properties 的正确写法local.properties是最容易写错的文件因为它对路径格式极其挑剔。Windows 上反斜杠是转义符直接写D:\Android\sdk会被 properties 解析器吞掉稳妥写法是全部用正斜杠。# local.properties —— 只放本机路径不要提交到版本库 # 正斜杠在 Windows / macOS / Linux 上都通用避免转义问题 sdk.dirD:/Android/sdk ndk.dirD:/Android/android-ndk-r16b # project.properties —— 编译目标与库工程引用 # target 必须与 SDK 里已安装的 Platform 完全一致写 android-26 就必须装 android-26 targetandroid-26 # 相对路径指向引擎自带的 Java 库工程 android.library.reference.1../cocos2d-x/cocos/platform/android/javatarget的值不是随便填的它决定了aapt用哪个android.jar编译。填了一个本机没装的 Platform构建会在最开始的阶段就退出错误信息是Unable to resolve target android-26此时去 SDK Manager 里补装对应版本即可不要试图改成android-35蒙混过关——高版本 Platform 会引入新的资源属性老模板解析不了。ndk.dir在老版本 SDK 里是可选的因为ndk-build可以通过 PATH 找到但一旦你在Application.mk里指定了APP_ABI构建脚本会强依赖这个变量缺了它某些 SDK 版本会静默跳过 native 编译最后打出来的 apk 里没有lib/目录运行直接闪退。这种「构建成功但运行崩」的问题最难查所以 ndk.dir 我建议一律写死。2.4 build.xml 与 SDK 模板的版本绑定关系build.xml本身只有十几行它干的事是把 SDK 目录下的tools/ant/build.xml导入进来真正的 clean、compile、dex、package 逻辑全在那个模板里。这意味着你的构建行为由 SDK 版本决定而不是由工程决定。?xml version1.0 encodingUTF-8? !-- 工程级 build.xml只做一件事导入 SDK 自带的 ant 构建模板 -- project nameMyGame defaulthelp !-- sdk.dir 从 local.properties 读取SDK Tools 26 之后该文件已被移除 -- import file${sdk.dir}/tools/ant/build.xml / /project所以「全套配置」的核心其实是一份匹配的 SDK。SDK Tools 25.2.5 及更早的版本里tools/ant/build.xml是完整存在的26 以后官方推荐 gradle这个文件就没了。手上只有新 SDK 的话两条路一是单独留一份 25.2.5 的tools目录通过-Dsdk.dir指过去二是从旧 SDK 里把tools/ant/build.xml连同tools/ant/下的支持文件一起拷进新 SDK 的tools/下。后者能跑但要接受一个事实模板对高版本 build-tools 的兼容性没保证aapt2相关的行为差异会在打包末期才暴露。3. 命令行跑通一次完整出包从 clean 到 debug 与 release3.1 环境变量清单一个都不能少ANT 构建对环境的依赖比 gradle 硬得多gradle 有 wrapper 可以自带 JDK 版本ANT 没有它完全信任你 shell 里的JAVA_HOME和ANT_HOME。下面这份是 Linux/macOS 构建机上的写法Windows 换成对应的set或系统环境变量即可。# JDK 必须是 89 以上会导致 dx 工具报 class file version 错误 export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 # ANT 建议 1.9.x1.10 对老 build.xml 的 task 定义有兼容性差异 export ANT_HOME/opt/apache-ant-1.9.16 export ANDROID_SDK_ROOT/opt/android-sdk export ANDROID_HOME$ANDROID_SDK_ROOT export NDK_ROOT/opt/android-ndk-r16b # 顺序有讲究JAVA_HOME/bin 放最前避免系统里另一个 java 抢占 export PATH$JAVA_HOME/bin:$ANT_HOME/bin:$NDK_ROOT:$PATH # 验证三件套版本不对就别往下走了 java -version # 期望 1.8.0_xxx ant -version # 期望 Apache Ant(TM) version 1.9.x ndk-build --version # 期望 GNU Make 相关输出说明 NDK 在 PATH 里参数说明JAVA_HOME必须指向 JDK 而不是 JRE指向 JRE 时 ant 会报Unable to locate tools.jar因为tools.jar只在 JDK 里ANT_HOME下必须有lib/ant-launcher.jar没有的话ant命令能启动但加载 task 会失败NDK_ROOT和 PATH 里的 ndk-build 是两回事前者给构建脚本读后者给 shell 调两个都配才稳妥。3.2 从 clean 到 debug apk环境就绪后进proj.android目录执行。第一次构建建议分开跑不要图省事一条命令串起来否则报错时不知道是 clean 阶段挂了还是编译阶段挂了。cd proj.android # 1. 清掉上一次的中间产物避免旧的 R.java / class 干扰 ant clean # 2. 编译 debug 包-v 输出详细日志第一次构建一定要加 ant debug -v # 3. 产物位置固定debug 包不需要签名 ls -lh bin/*-debug.apk逻辑说明ant clean会删除bin/、gen/、obj/三个目录其中gen/放的是 aapt 生成的R.java这个文件不清理是很多「资源 id 找不到」问题的源头ant debug会依次触发资源编译、Java 编译、native 编译若配置了 ndk、dex 转换、打包、debug 签名六个阶段任一失败都会中断加-v是为了看到底停在哪一步。如果 SDK 路径不是从local.properties读到的可以在命令行覆盖这在多 SDK 并存的构建机上很有用# 命令行覆盖 sdk.dir优先级高于 local.properties ant -Dsdk.dir/opt/android-sdk-25.2.5 debug3.3 release 包与产物路径release 和 debug 的差别只在最后两步是否签名、是否 zipalign。没有配置签名信息的工程ant release会正常跑完并生成一个-unsigned.apk很多人看到构建成功就以为完事了装到手机上才发现装不上。# 未配置签名时产出的是未签名包 ant release ls -lh bin/*-release*.apk # 配置好 ant.properties 后直接产出已签名包 ant release # 已签名产物通常带 -release.apk 后缀具体命名随 SDK 版本略有差异 ls -lh bin/产物命名在不同 SDK 版本下不完全一致有的是MyGame-release.apk有的是MyGame-release-unsigned.apk判断标准不是文件名而是jarsigner -verify的结果。这一步在最后一章会给出自检脚本。3.4 用 cocos 命令行间接触发如果工程还在用 Cocos 自带的命令行工具老版本的cocos compile -p android默认调的就是 ANT加--android-studio才切 gradle。这条路径的好处是它会自动帮你处理 assets 拷贝和AndroidManifest.xml的包名替换省掉手工同步的步骤。# 在工程根目录执行不带 --android-studio 即为 ANT 构建 cocos compile -p android -m release --ap android-26 # 只做构建不做安装产物落在 proj.android/bin 下 ls -lh proj.android/bin/参数说明-m release指定构建模式--ap指定 Android Platform 版本这个值要和project.properties里的target保持一致两边不一致时以命令行参数为准但生成的清单里可能残留旧值发版前要核对。这条命令适合日常出包排查具体错误时还是建议回到ant原始命令日志更干净。4. 签名、ABI 与版本号四个必须写死的构建参数4.1 ant.properties 里的四个签名键release 包的签名信息有三种给法写进ant.properties、命令行-D传入、环境变量。工程化程度最高的是第一种但要注意这个文件含明文密码绝对不能进版本库。# ant.properties —— release 签名配置加入 .gitignore # keystore 用正斜杠绝对路径相对路径在不同工作目录下会失效 key.store/home/build/keys/release.keystore key.store.passwordYourStorePass123 key.aliasreleasekey key.alias.passwordYourKeyPass123四个键的含义key.store是 keystore 文件路径必须存在且可读key.store.password是 keystore 整体口令key.alias是里面某一个条目的别名一个 keystore 可以有多个别名填错会报Certificate chain not foundkey.alias.password是该别名单独的口令很多工具在创建 keystore 时默认两者相同但它们是两个独立的值。密码里如果出现$、#、!这类字符在 properties 文件里会被当成特殊符号处理$后面跟变量名会被替换成空串。血泪经验是构建专用 keystore 的口令只用字母加数字别为了「安全」加一堆符号最后在 CI 上排查半天。别名和口令不确定时用 keytool 反查# 列出 keystore 里所有别名并校验口令是否正确 keytool -list -v -keystore /home/build/keys/release.keystore -storepass YourStorePass1234.2 APP_ABI 裁剪与 STL 选择ANT 链路下 native 编译由jni/Application.mk控制这个文件决定打哪几个 CPU 架构的 so直接关系到包体积和兼容性。# jni/Application.mk # 老 NDKr16 及以前用 gnustl_staticr18 之后必须换成 c_static APP_STL : gnustl_static # 开启 C 异常与 RTTICocos 的某些模块依赖这两项 APP_CPPFLAGS : -frtti -fexceptions -stdc11 -fsigned-char # 只打主流两个架构包体积能省将近一半 APP_ABI : armeabi-v7a arm64-v8a # 最低支持的系统版本写太低会在高版本系统上有兼容性告警 APP_PLATFORM : android-19参数说明APP_ABI每多一个架构lib/目录下就多一份 sox86和x86_64只对模拟器有意义真机发版可以去掉APP_PLATFORM影响链接时使用的系统 API 符号设成android-19就意味着放弃 4.4 以下的设备这个值不能高于project.properties里的targetAPP_STL与 NDK 版本强绑定用错版本的 STL 会在链接期报一堆undefined reference to std::__ndk1::之类的符号缺失。一个常见的误用是把APP_ABI写成all看着省事实际上会把 mips、mips64 这些早已废弃的架构也编进去构建时间翻三倍包体积涨一倍收益为零。4.3 versionCode 与渠道串的处理版本号写在AndroidManifest.xml的manifest节点上ANT 构建时直接读这个值没有 gradle 那种versionCode的脚本化覆盖能力。稳妥做法是发版前用脚本改清单而不是靠命令行传参。!-- AndroidManifest.xml 片段 -- manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.mygame android:versionCode12 android:versionName1.2.0 !-- versionCode 必须单调递增否则覆盖安装会失败 --渠道串的处理方式有两种一是在清单里写meta-data android:nameCHANNEL android:valueofficial /每个渠道改完重新打包二是保持一份模板构建前用 sed 替换CHANNEL占位符。后者更适合一次出多个渠道包。# 批量改渠道串再构建先备份清单避免改坏原文件 cp AndroidManifest.xml AndroidManifest.xml.bak for ch in official oppo vivo; do sed -i s/android:value\__CHANNEL__\/android:value\$ch\/ AndroidManifest.xml ant clean release /dev/null cp bin/*-release.apk ../dist/mygame-$ch.apk # 每轮结束恢复占位符否则第二轮匹配不上 cp AndroidManifest.xml.bak AndroidManifest.xml done这段脚本的关键在最后那行恢复操作。sed 是就地修改第一轮替换掉占位符之后第二轮再匹配__CHANNEL__就找不到了产出的包渠道串还停留在上一轮的值——这个坑我在渠道包上踩过一次二十个包全是同一个渠道只能全部重打。5. 避坑与排查五个把构建卡死的现场5.1 环境与路径类问题现象一Error: Could not find or load main class org.apache.tools.ant.launch.Launcher。原因通常是ANT_HOME没设、设错或者路径里带空格和中文启动脚本拼 classpath 时被截断。解决办法是把 ANT 解压到纯英文无空格路径确认$ANT_HOME/lib/ant-launcher.jar存在然后重新 export 一次环境变量并source生效。改完先用ant -version验证别急着进工程目录。现象二sdk.dir is missing但 local.properties 明明写了。三种可能文件编码是 UTF-16 或带 BOMproperties 解析器读不到第一行文件放在了工程根目录而不是proj.android下路径里用了未转义的反斜杠。解决方式是统一存成 UTF-8 无 BOM路径全部用正斜杠并用ant -Dsdk.dir... debug命令行覆盖一次验证是不是文件本身的问题。现象三aapt: error while loading shared libraries: libz.so.1。这是 64 位 Linux 上跑 32 位 build-tools 的经典报错。原因是老版本aapt是 32 位可执行文件系统没装 32 位运行库。解决是装齐lib32z1、lib32ncurses5、lib32stdc6三个包装完ldd $(which aapt)不再有 not found 即可。如果装不了另一条路是换一个带 64 位 aapt 的 build-tools 版本但要同步验证 ant 模板是否兼容。5.2 编译与签名类问题现象四trouble processing java/lang/invoke/MethodHandle.class或unsupported class file version 52.0。出现这个说明 JDK 版本和 build-tools 的 dx 工具代际不匹配多半是用 JDK 8 编译但工程里混进了用高版本 JDK 编译的 jar 包或者反之。解决方式是确认JAVA_HOME指向 JDK 8然后ant clean全清一次——不清的话bin/里残留的 class 文件还是老版本改了环境也没用。第三方 jar 若确实是高版本编译的只能重新编译那个 jar没有别的捷径。现象五release 构建成功但装不上或jarsigner: Certificate chain not found for: xxx。前者是没做 zipalign后者是ant.properties里的key.alias与实际 keystore 里的别名不一致。先用keytool -list确认别名拼写再用jarsigner -verify -verbose bin/xxx-release.apk验证签名是否真的写进去了。未对齐的包在部分机型上能装但启动就崩所以 zipalign 这一步不能省老模板一般在 release 流程末尾自动执行被手动改过 build.xml 的工程要单独确认。6. 把 ANT 打包压成一条可重放命令脚本化与产物自检前面所有步骤跑通之后真正的工程价值在于「换台机器也能一条命令出包」。我一般会写一个build_android.sh把环境校验、清理、构建、签名校验、产物归档串起来任何一步失败就退出不留半成品。#!/usr/bin/env bash set -euo pipefail # 前置校验版本不对直接退出不做无谓的构建 java -version 21 | grep -q 1.8 || { echo JDK 必须是 1.8; exit 1; } test -f $ANDROID_SDK_ROOT/tools/ant/build.xml || { echo SDK 缺少 ant 模板; exit 1; } cd proj.android ant clean ant release APK$(ls bin/*-release*.apk | head -n 1) # 签名校验未签名的包在这里就会被拦下 jarsigner -verify $APK /dev/null || { echo 签名校验失败; exit 1; } # 对齐校验zipalign -c 返回非 0 表示未对齐 $ANDROID_SDK_ROOT/build-tools/25.0.3/zipalign -c 4 $APK || { echo APK 未对齐; exit 1; } mkdir -p ../dist cp $APK ../dist/mygame-$(date %Y%m%d%H%M).apk echo 构建完成$APK这段脚本里最值得抄的是两道校验jarsigner -verify能挡住「构建成功但签名为空」的情况zipalign -c 4能挡住「能装但运行崩」的对齐问题。两者都不依赖构建日志直接对产物做事实判断比看日志里那句「BUILD SUCCESSFUL」可靠得多。还有个小技巧在dist/目录里保留最近五个包并按时间戳命名回滚时能快速定位到某个版本对应的 apk不用重新构建。这套流程我在几个老工程上用了两年多从那以后每次动 SDK 或 JDK 之前都强制先跑一遍这个脚本做基线验证——环境一变基线立刻能告诉你炸在哪一步。希望帮到你。本文还有配套的精品资源点击获取

Cocos安卓ANT打包全链路：版本对齐、签名与排错

相关推荐

Agent技能库越用越笨？SkillBrew多目标精炼实现技能库“做减法”

雷达信号处理链路拆解：DBF、相干积累与目标角度测量

CCF-CSP认证考点知识要求与高效备考策略：从算法题到保研实习

更多资讯

Codex：从代码补全到软件工程智能体的范式跃迁

销售易CRM系统实战指南：配置、迁移与性能优化

社交媒体主页工具开发：技术架构与盈利模式解析

C语言职工管理系统：链表与文件读写打通增删改查实战

工业AI操作系统如何落地？西门子新技术的实战拆解

Token市场海外对标：从API报错到大模型定价的生态密码

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？