企业官网建设流程全解析

简介：这份资源面向使用Cocos引擎开发游戏、需要在Mac环境下完成安卓打包的开发者，尤其适合刚接触ANT构建流程、希望系统掌握从编译到签名发布全链路的中级开发者。资源包共1634个文件，以1525个html文档为主体，辅以24个pom、24个jar、15个xsl及若干cmd、bat脚本与xml配置，压缩包约9.12MB，完整覆盖Apache Ant工具链的文档、依赖库与构建脚本，便于离线查阅与本地部署。目前已有441人学习下载。内容围绕ANT安装与环境变量配置、Cocos项目project.android目录结构、build.xml参数调整、keystore签名设置、ant release打包执行以及编译优化与调试排错等环节展开，读者可据此搭建可复用的安卓打包环境，理解构建脚本各参数含义，并掌握APK生成、签名与发布前的验证思路，减少因配置不当导致的编译失败与资源缺失问题。

1. 从一次打包失败说起：ANT 环境到底卡在哪

上周帮一个做休闲游戏的朋友看打包问题，Cocos Creator 里点“构建 Android 包”，控制台刷了十几行红字，最后停在BUILD FAILED，提示找不到ant或者sdk.dir没配。他以为重装 Cocos 就能解决，结果折腾一下午，问题还在。这个场景太常见了——Cocos 安卓打包本身不复杂，真正卡人的是 ANT 这套老构建工具的环境配置。很多人第一次接触 ANT 是在 Cocos 的 Android 构建面板里，看到“ANT 版本”“NDK 路径”“SDK 路径”几个输入框就懵了。装不好会怎样？轻则构建报错、APK 出不来，重则连编辑器都识别不到 Android 环境，构建按钮直接灰掉。这篇笔记适合正在用 Cocos Creator 做安卓打包、被 ANT 配置卡住的开发者，尤其是从 Unity 或纯 Android Studio 转过来、对 ANT 这套东西不熟的人。我会把版本选择、下载、环境变量、Cocos 里的路径填写、验证和排错按顺序走一遍，照着做基本能跑通。

2. 装前先定版本：ANT、JDK、SDK 的搭配关系

2.1 为什么 Cocos 安卓打包还在用 ANT

Cocos Creator 的 Android 构建底层走的是 Gradle，但早期版本和很多教程里仍然保留 ANT 构建选项。ANT 是 Apache 的一个 Java 构建工具，用 XML 描述构建过程，比 Gradle 轻量，但配置全靠手动。Cocos 在构建面板里让你填 ANT 路径，本质是让构建脚本能找到ant命令去执行build.xml。如果你用的是 Cocos Creator 2.x 系列，ANT 几乎是必配项；3.x 虽然默认 Gradle，但部分定制构建流程仍会回退到 ANT。所以先把 ANT 装明白，后面换 Gradle 也不会慌。

2.2 版本对照：别拿最新版硬套

ANT 不是越新越好。Cocos 官方文档和社区实践里，稳定组合是 ANT 1.9.x 或 1.10.x，JDK 用 8（1.8），Android SDK 用 API 26 到 30 之间的版本。我一般会选 ANT 1.10.14，JDK 1.8.0_301，SDK Platform 29，Build-Tools 29.0.3。这个组合在 Windows 和 macOS 上都验证过，报错最少。如果你用 JDK 11 或 17，ANT 1.10 虽然能跑，但 Cocos 的构建脚本里有些javac参数会不兼容，容易出unsupported class file version之类的错。所以别图省事用系统里已有的高版本 JDK，单独给 Cocos 配一个 JDK 8 更稳。

2.3 下载渠道与目录规划

ANT 去 Apache 官网下载apache-ant-1.10.14-bin.zip，解压到不含中文和空格的路径，比如D:\dev\apache-ant-1.10.14。JDK 8 用 Oracle JDK 或 OpenJDK 都行，装到D:\dev\jdk1.8.0_301。Android SDK 建议用命令行工具commandlinetools自己装，不要用 Android Studio 自带的，避免路径混乱。目录规划原则：所有开发工具放在同一个盘符下的dev目录，路径全英文，后面配环境变量和 Cocos 路径时能省很多事。

3. 配置环境变量：三个路径写错就白装

3.1 JAVA_HOME 和 Path 的写法

装完 JDK 后，先配JAVA_HOME。Windows 下新建系统变量JAVA_HOME，值为D:\dev\jdk1.8.0_301，注意不要带\bin。然后在Path里加%JAVA_HOME%\bin。macOS 或 Linux 在~/.bash_profile或~/.zshrc里写：

export JAVA_HOME=/Users/yourname/dev/jdk1.8.0_301 export PATH=$JAVA_HOME/bin:$PATH

这里的关键是JAVA_HOME指向 JDK 根目录，PATH里加bin。很多人把JAVA_HOME写成.../bin，结果 ANT 执行时找不到tools.jar，报Unable to locate tools.jar。改完执行source ~/.zshrc或重启终端，用java -version确认输出是 1.8。

3.2 ANT_HOME 与 Path 的配合

ANT 同样需要ANT_HOME和Path。Windows 新建ANT_HOME为D:\dev\apache-ant-1.10.14，Path加%ANT_HOME%\bin。macOS 下：

export ANT_HOME=/Users/yourname/dev/apache-ant-1.10.14 export PATH=$ANT_HOME/bin:$PATH

注意ANT_HOME不要指向bin目录，否则ant -version会报ANT_HOME is set incorrectly。配完在终端执行ant -version，正常输出Apache Ant(TM) version 1.10.14 compiled on ...。如果提示command not found，检查Path里是否加了%ANT_HOME%\bin或$ANT_HOME/bin。

3.3 ANDROID_HOME 和 SDK 路径

Android SDK 需要配ANDROID_HOME，指向 SDK 根目录，比如D:\dev\android-sdk。Path里加%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\tools。macOS 下：

export ANDROID_HOME=/Users/yourname/dev/android-sdk export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$PATH

配完后用adb version验证，能输出版本号说明 SDK 路径没问题。如果adb找不到，多半是platform-tools没加进Path。这三个环境变量配完，重启一次终端或命令行，让所有变量生效。

提示：Windows 下改完环境变量一定要新开一个 cmd 或 PowerShell 窗口，旧窗口不会自动加载新变量。

4. 在 Cocos 里填路径：构建面板的四个输入框

4.1 打开构建面板与 Android 选项

在 Cocos Creator 里点“项目”->“构建发布”，选择 Android 平台。面板里会出现几个关键输入框：NDK 路径、SDK 路径、ANT 路径、JDK 路径。这些路径必须和你在系统环境变量里配的一致，但 Cocos 不读环境变量，它只认你在这里填的绝对路径。所以即使系统里ant -version正常，这里填错照样构建失败。

4.2 四个路径的填写规则

• JDK 路径：填 JDK 根目录，如D:\dev\jdk1.8.0_301，不要填bin。
• SDK 路径：填 Android SDK 根目录，如D:\dev\android-sdk。
• ANT 路径：填 ANT 根目录，如D:\dev\apache-ant-1.10.14。
• NDK 路径：填 NDK 根目录，如D:\dev\android-ndk-r21e。

macOS 下路径类似/Users/yourname/dev/...。填完后点“构建”，Cocos 会调用这些路径下的工具。如果某个路径填错，控制台会明确提示哪个工具找不到，比如ANT path is invalid或JDK not found。

4.3 构建参数与常见选项

构建面板里还有几个参数值得注意：包名用反域名格式，如com.example.game；API Level选 29；App ABI按需勾选armeabi-v7a和arm64-v8a。如果只是本地测试，可以只勾一个 ABI，减少构建时间。Keystore不填也能出 debug 包，但正式发布必须配签名。这些参数和 ANT 配置不直接冲突，但包名或 API Level 写错会导致 ANT 构建阶段报aapt错误。

# 构建完成后，可以在项目目录下用 ant 手动验证 cd build/jsb-default/frameworks/runtime-src/proj.android ant clean ant debug

这段命令是在 Cocos 构建生成的 Android 工程目录里手动跑 ANT，用来验证 ANT 本身是否配置正确。ant clean清理旧输出，ant debug编译 debug 包。如果这里能成功，说明 ANT、JDK、SDK 三者配合没问题，Cocos 面板里的构建失败多半是路径填写或参数问题。

5. 避坑与排查：五个高频翻车现场

5.1 现象：Unable to locate tools.jar

原因：JAVA_HOME指向了 JRE 而不是 JDK，或者指向了bin目录。ANT 需要 JDK 里的tools.jar，JRE 没有这个文件。解决：确认JAVA_HOME是 JDK 根目录，且该目录下lib文件夹里有tools.jar。如果用的是 JDK 11 以上，tools.jar已经被移除，必须换回 JDK 8。

5.2 现象：sdk.dir is missing

原因：Cocos 构建时会在 Android 工程目录下找local.properties文件，里面需要写sdk.dir。如果 Cocos 面板里 SDK 路径填了但没生成这个文件，ANT 就找不到 SDK。解决：手动在proj.android目录下新建local.properties，写入sdk.dir=D\:\\dev\\android-sdk（Windows 注意转义），macOS 写sdk.dir=/Users/yourname/dev/android-sdk。

5.3 现象：ant: command not found但系统里能跑

原因：Cocos 构建时用的 shell 环境和你终端里的不一样，它可能没加载你的PATH。解决：在 Cocos 面板里直接填 ANT 根目录的绝对路径，不要依赖环境变量。如果面板里已经填了还报这个错，检查路径里是否有空格或中文，ANT 对路径中的空格很敏感。

5.4 现象：构建卡在aapt或dx阶段

原因：Build-Tools 版本和 SDK Platform 版本不匹配，或者aapt没有执行权限。解决：确保 SDK 里安装了对应版本的 Build-Tools，比如 API 29 配 Build-Tools 29.0.3。macOS 下用chmod +x给aapt和dx加执行权限。Windows 下检查杀毒软件是否拦截了aapt.exe。

5.5 现象：JDK 版本冲突导致unsupported class file version

原因：系统里装了多个 JDK，Cocos 或 ANT 调用了高版本 JDK 去编译低版本目标。解决：在 Cocos 面板里明确指定 JDK 8 的路径，不要用系统默认。同时检查JAVA_HOME是否被其他工具改过。我一般会在构建前用java -version再确认一次。

注意：每次改完环境变量或 Cocos 面板路径，建议先关掉 Cocos Creator 再重新打开，避免缓存旧路径。

6. 装完怎么验证：从命令行到 APK 的完整检查

装完不是看ant -version有输出就完事，得走一遍完整链路。我习惯按这个顺序验证：先确认 JDK 版本，再确认 ANT 能独立构建一个空工程，最后回到 Cocos 出包。第一步，终端执行java -version，输出必须是1.8.0_xxx，如果是 11 或 17，后面大概率出问题。第二步，ant -version输出 1.10.14。第三步，adb version能显示版本号。这三条都过了，说明基础环境没问题。

接下来找一个 Cocos 的空项目，或者直接用你正在做的项目，在构建面板里填好四个路径，点构建。构建过程中盯着控制台，如果出现BUILD SUCCESSFUL，说明 ANT 链路通了。构建完成后，去build/jsb-default/frameworks/runtime-src/proj.android/bin目录下找*.apk文件。用adb install装到真机或模拟器上，能启动、不闪退，才算真正跑通。

# 验证 APK 是否生成并安装 ls build/jsb-default/frameworks/runtime-src/proj.android/bin/*.apk adb install -r build/jsb-default/frameworks/runtime-src/proj.android/bin/yourgame-debug.apk adb shell am start -n com.example.game/org.cocos2dx.lua.AppActivity

这段命令先列出 APK 文件，确认构建产物存在；然后用adb install -r覆盖安装；最后用am start启动应用。如果启动后黑屏或闪退，用adb logcat看日志，常见的是libcocos2djs.so没打包进去，检查App ABI是否勾选了对应架构。

还有一个容易忽略的点：Cocos 构建时会在proj.android下生成build.xml，这个文件是 ANT 的构建脚本。如果手动改过这个文件，下次 Cocos 构建会覆盖掉。所以不要直接改build.xml，要改就在 Cocos 的构建模板里改。我一般会在验证通过后，把整个proj.android目录备份一份，下次换机器直接对比路径和配置，省得重新踩坑。

从那以后我每次配新机器，都强制走一遍“命令行验证 -> Cocos 构建 -> 真机安装”这三步，不跳过任何一步。因为 ANT 这套东西，只要有一个路径不对，报错信息往往指向别处，很容易被带偏。希望帮到你。

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