企业官网建设流程全解析

简介：面向在 Mac 环境下进行 Cocos 跨平台游戏开发的安卓打包初学者与进阶开发者，这份资源提供 Apache ANT 全套配置工具与配套说明，用于解决 Cocos 项目编译、签名与生成 APK 的完整流程问题。压缩包共 1634 个文件，约 9.12MB，以 1525 个 html 文档为主体，辅以 24 个 jar 与 24 个 pom 构建依赖、15 个 xsl 样式表，以及 cmd、bat、sh 类启动脚本和 properties 配置样例，基本覆盖 ANT 运行所需的库、文档与命令行入口。已有 443 人学习下载，说明其在 Cocos 安卓打包场景中具备一定参考价值。读者可借助其中的构建脚本与配置样例，对照理解 build.xml 参数调整、keystore 签名设置及 ant release 执行链路，并参考文档排查编译错误与资源缺失问题，从而缩短环境搭建与打包调试的摸索时间。

1. 安卓打包卡在 ANT 这一步：一份能直接落地的 Cocos 构建配置

Cocos 项目在编辑器里跑得好好的，一点「构建」就卡在 Android 原生打包环节，报错信息翻来覆去就是sdk.dir、ant、build.xml这几个词——这是很多做 Cocos 安卓打包的开发者都遇到过的场景。这份「Cocos 安卓打包 ANT 全套配置」资源，解决的就是从 Cocos 构建产物到 APK 落地这一段最容易翻车的基础设施问题：JDK、Android SDK、NDK、ANT 四件套的版本对齐，环境变量怎么设，local.properties和build.xml怎么改，以及签名和渠道参数怎么塞进去。它适合两类人：一是刚接手 Cocos 项目、被安卓打包环境折腾到怀疑人生的新手；二是需要把打包流程固化下来、做批量出包的老手。下面按「这套配置是什么 → 怎么一步步搭起来 → 坑在哪 → 怎么验证」的顺序拆开讲，每一步都能照着复现。

2. 先把四件套版本对齐：JDK、SDK、NDK、ANT 的选型逻辑

ANT 打包在今天的 Android 生态里算是「老派」路线，但它并没有消失——Cocos 的很多历史工程、定制化出包脚本、以及需要精细控制AndroidManifest.xml合并过程的场景，仍然依赖 ANT 这套构建链。选它的理由很实际：构建过程透明，每一步都是可读的 XML 和命令行，出问题能定位到具体任务，不像某些封装过深的构建工具那样把错误吞进黑匣子。代价是版本耦合极紧，四件套里任何一个版本跳错，报错都指向别处。

2.1 为什么 ANT 路线对版本如此敏感

ANT 本身只是个构建调度器，真正干活的是它调用的javac、aapt、dx（或d8）、apksigner这些工具，而这些工具全部来自 JDK 和 Android SDK。Cocos 生成的build.xml里写死了不少任务名和参数格式，比如dx的调用方式在 Build Tools 26 之后就被d8取代，老build.xml直接调dx就会找不到可执行文件。所以版本对齐不是「尽量一致」，而是「必须落在 Cocos 该版本模板支持的区间内」。

常见做法是：JDK 用 8（对应 Cocos 2.x 时代的模板），Android SDK Build Tools 控制在 28～30 之间，NDK 用 r19c 或 r21 这类与引擎Android.mk兼容的版本，ANT 用 1.10.x。这套组合不是唯一解，但它是踩坑最少的组合。我一般会先把这四个版本号写进项目根目录的一个env-versions.txt里，团队里谁换机器都照抄，避免「我这能打包你那不能」的玄学问题。

2.2 环境变量与local.properties的写法

版本选好之后，落地第一步是把路径告诉构建系统。ANT 读的是环境变量ANT_HOME和JAVA_HOME，Android SDK 路径则通过项目里的local.properties传给build.xml。这两处任何一处写错，报错都会伪装成「找不到工具」而不是「路径错」。

# 以 Linux/macOS 为例，写入 ~/.bashrc 或 ~/.zshrc export JAVA_HOME=/opt/jdk8 export ANT_HOME=/opt/ant-1.10.12 export ANDROID_SDK_ROOT=/opt/android-sdk export ANDROID_NDK_ROOT=/opt/android-ndk-r21e export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$ANDROID_SDK_ROOT/platform-tools:$PATH # 验证四件套是否都能被找到 java -version ant -version ls $ANDROID_SDK_ROOT/build-tools ls $ANDROID_NDK_ROOT/toolchains

这段脚本的逻辑是先把四个根路径固定下来，再把java、ant、adb加进PATH。参数说明：JAVA_HOME必须指向 JDK 根目录而不是bin；ANDROID_SDK_ROOT是新版变量名，老脚本可能读ANDROID_HOME，两个都设上最稳；ANDROID_NDK_ROOT只在需要编译原生库时被读取。验证命令里ls build-tools是为了确认目标版本目录真实存在，很多人 SDK 装了但没装对应 Build Tools，ls一跑就露馅。

local.properties放在 Cocos 构建产物目录（通常是proj.android或build/android/proj）下，内容只有一行：

# 指向 Android SDK 根目录，注意用正斜杠，Windows 下也别用反斜杠 sdk.dir=/opt/android-sdk

提示：local.properties不要提交到版本库，它因机器而异；团队里用模板文件local.properties.sample代替，构建前复制改名。

2.3 用ant debug跑通第一条构建链

环境就绪后，先别急着出正式包，用 debug 构建验证整条链路。进入 Cocos 生成的安卓工程目录，执行：

cd build/android/proj # 清理旧产物，避免增量构建掩盖问题 ant clean # 执行 debug 构建，输出到 bin/ 目录 ant debug -Dverbose=true

ant clean会删掉bin/、gen/、obj/这些中间目录，第一次跑务必执行，否则残留的R.java可能让新资源不生效。ant debug走的是build.xml里的 debug target，自动用 debug keystore 签名，不需要你配签名文件。-Dverbose=true是让 ANT 打印每个任务的详细输出，第一次跑强烈建议加上，能看清它到底调了哪个aapt、哪个dx。构建成功后产物在bin/下，文件名形如项目名-debug.apk，用adb install装到真机验证。

如果这一步就报错，先看报错里出现的工具名：报aapt找不到，查 Build Tools 版本目录；报dx找不到，说明模板太老而 Build Tools 太新，需要降 Build Tools 或改build.xml里的dx为d8；报javac的source 1.7不支持，说明 JDK 版本过高。这三类占了首次构建失败的大头。

3. 改build.xml与签名配置：把出包参数真正捏在手里

debug 跑通只证明链路是活的，正式出包还得处理签名、渠道参数、AndroidManifest.xml合并这几件事。ANT 路线的优势在这里体现得最明显——所有参数都在 XML 和 properties 文件里，改起来一目了然。

3.1 正式签名：ant.properties与 keystore 的对接

Cocos 生成的build.xml里，release target 会读取ant.properties中的签名配置。你需要准备一个 keystore，然后把别名、密码、路径写进去：

# ant.properties，放在 proj.android 根目录 key.store=../keystore/release.keystore key.store.password=你的store密码 key.alias=release key.alias.password=你的alias密码

参数说明：key.store用相对路径时是相对build.xml所在目录，建议统一放工程外的keystore/目录并加进.gitignore；key.alias必须和keytool -list里显示的一致，大小写敏感。生成 keystore 的命令：

keytool -genkeypair -v \ -keystore release.keystore \ -alias release \ -keyalg RSA -keysize 2048 -validity 36500 \ -storepass 你的store密码 -keypass 你的alias密码 \ -dname "CN=Demo, OU=Dev, O=Demo, L=City, ST=State, C=CN"

-validity 36500是给足有效期，避免几年后包过期；-dname里的字段按需改，但CN别留空。生成后执行ant release，产物在bin/下，未签名或已签名的 APK 取决于模板版本，较新模板会直接调apksigner完成签名。

3.2 渠道参数注入：用 properties 做多包差异化

批量出包时，不同渠道要改AndroidManifest.xml里的渠道号、应用名甚至包名。硬改 XML 不可维护，正确做法是把差异抽成 properties，在build.xml里用manifestmerger或replace任务注入。常见做法是在ant.properties里加渠道变量：

# 渠道相关变量，构建时用 -D 覆盖 channel.name=default app.label=Demo

然后在build.xml的 release target 前插入一段替换逻辑：

<!-- 在 build.xml 中，编译前替换 Manifest 占位符 --> <target name="-pre-build"> <replace file="AndroidManifest.xml" token="@CHANNEL_NAME@" value="${channel.name}" /> <replace file="res/values/strings.xml" token="@APP_LABEL@" value="${app.label}" /> </target>

逻辑说明：-pre-build是 ANT 约定的前置钩子，会在编译前执行；replace任务把 XML 里的占位符替换成 properties 里的值。参数上，token要和AndroidManifest.xml里写的占位符完全一致，value引用${}变量。批量出包时用ant release -Dchannel.name=huawei -Dapp.label=Demo华为版覆盖，一条命令一个渠道，脚本里循环调用即可。

注意：replace是原地修改文件，连续构建不同渠道时，第二次会找不到占位符。稳妥做法是每次构建前从模板AndroidManifest.xml.tpl复制一份再替换，别直接改源文件。

3.3AndroidManifest.xml合并与aapt资源冲突排查

Cocos 工程常引入多个第三方 SDK 的 aar 或 res，aapt在合并资源时容易报Resource entry already defined。这类冲突的根因是不同库定义了同名资源（如ic_launcher、app_name）。排查方法是看aapt报错里给出的两个来源路径，判断哪个是主工程、哪个是库，然后在主工程的res/values/下用<resources>覆盖，或在build.xml的aapt任务里加--auto-add-overlay参数让后引入的覆盖先引入的。

<!-- build.xml 中 aapt 任务片段，加自动覆盖参数 --> <aapt executable="${aapt}" resource="${resource.dir}" manifest="AndroidManifest.xml" autoverlay="true" ... />

autoverlay="true"对应命令行--auto-add-overlay，作用是允许后加入的资源覆盖同名资源，而不是直接报错。这个参数在引入多个 UI 库时几乎是必开项，但要注意覆盖顺序依赖引入顺序，出包后务必抽查图标、字符串是否被意外替换。

4. 避坑清单：ANT 打包最常见的五类翻车

4.1 报sdk.dir未设置，但local.properties明明写了

现象：ant debug报sdk.dir is missing，打开local.properties路径正确。原因多半是构建目录不对——Cocos 有时在proj.android和build/android/proj各有一份工程，你改的那份不是build.xml实际所在目录。解决：在报错目录下执行pwd，确认build.xml和local.properties在同一层，不在就补一份。

4.2dx报unsupported class file version 52.0

现象：编译通过，打包阶段dx报 class 版本不支持。原因是 JDK 8 编译出的 class 是 52.0，而老版dx只认到 51.0。解决：要么把 Build Tools 升到 28 以上改用d8，要么在build.xml的javac任务里加source="1.7" target="1.7"降级编译。前者更推荐，后者只是临时绕过。

4.3 签名后安装报INSTALL_PARSE_FAILED_NO_CERTIFICATES

现象：ant release成功，adb install报无证书。原因是模板调的是jarsigner而目标设备要求 v2 签名，或ant.properties里密码含特殊字符被 properties 解析截断。解决：确认用apksigner签名，密码里若有#、=等字符，在 properties 里用\转义，或改用-Dkey.store.password=命令行传入。

4.4 渠道替换后第二次构建失效

现象：第一次出华为包正常，第二次出小米包应用名还是华为。原因就是 3.2 提到的replace原地修改，占位符已被替换掉。解决：构建脚本里每次先cp AndroidManifest.xml.tpl AndroidManifest.xml，再执行ant release，把「复制模板」作为出包流程的第一步固化下来。

4.5 NDK 编译报APP_PLATFORM不匹配

现象：含原生库的工程在ndk-build阶段报APP_PLATFORM android-XX is not supported。原因是 NDK 版本与Application.mk里写的APP_PLATFORM不匹配，r21 之后最低支持 android-16 且部分旧平台被移除。解决：打开Application.mk，把APP_PLATFORM调到 NDK 支持的区间（如android-21），同时确认APP_ABI只保留目标架构，减少构建时间。

5. 用脚本固化整条链路：一次配置，长期可复现

单次手动跑通不算本事，能把这套配置固化成脚本、换机器换人都能一键出包，才算真正落地。我一般会在工程根目录放一个build_android.sh，把环境检查、模板复制、渠道循环、产物归档串起来，配合 CI 使用。

#!/usr/bin/env bash set -euo pipefail # 1. 环境自检：四件套缺一不可 for cmd in java ant adb; do command -v "$cmd" >/dev/null || { echo "缺少 $cmd"; exit 1; } done [ -d "$ANDROID_SDK_ROOT/build-tools/30.0.3" ] || { echo "Build Tools 版本缺失"; exit 1; } # 2. 渠道列表，按需增删 CHANNELS=("default" "channel_a" "channel_b") cd build/android/proj ant clean for ch in "${CHANNELS[@]}"; do # 每次从模板恢复 Manifest，避免 replace 残留 cp AndroidManifest.xml.tpl AndroidManifest.xml ant release -Dchannel.name="$ch" -Dapp.label="Demo-$ch" # 产物按渠道归档，文件名带渠道和时间戳 mkdir -p ../../dist cp bin/*-release.apk "../../dist/demo-${ch}-$(date +%Y%m%d%H%M).apk" done echo "全部渠道出包完成，产物在 dist/ 目录"

脚本逻辑分四段：环境自检用command -v确认命令存在、用目录判断确认 Build Tools 版本，缺任何一项直接退出，避免跑到一半才报错；CHANNELS数组是渠道清单，增删渠道只改这一行；循环里先cp模板再ant release，这是 4.4 那个坑的根治办法；最后按渠道和时间戳归档，方便回溯哪个包是什么时候出的。参数上，set -euo pipefail让脚本遇错即停，-D覆盖的变量名必须和build.xml里的${}一致。

验证方法很简单：删掉bin/和dist/，从零跑一遍脚本，看dist/下是否每个渠道一个包、包名是否带对应渠道、装到真机上应用名是否正确。再故意把ANDROID_SDK_ROOT改错，确认脚本在自检阶段就退出而不是跑到签名才崩——这一步能验证你的「后悔药」是否有效。

从那以后我每次接手新的 Cocos 安卓工程，都强制先跑一遍这个脚本的环境自检段，确认四件套版本和路径没问题再动业务代码，省下的排查时间远比写脚本花的多。希望帮到你。

本文还有配套的精品资源，点击获取