去年年底我把项目从 Cocos Creator 2.x 迁到 3.8.7第一次在构建发布面板里选中“Android”平台时我以为只是填个包名点一下生成结果光环境配置就耗了两个晚上。群里同样玩 3.8.7 的朋友也轮番踩坑有人 SDK 路径怎么填都报错有人 Gradle 同步直接卡死好不容易出包了装到手机上启动就闪退。所以这篇东西不是照着官方文档抄一遍而是把 CocosCreator 3.8.7 安卓打包配置的完整链路——版本对齐、构建面板参数、原生工程后半程、报错排查思路——全部摊开讲。适合刚从 2.x 迁到 3.x 的团队、第一次接触 Creator 安卓打包的开发者也适合那种看文档觉得都会、上手实操总翻车的老哥。1. 3.8.7 的安卓环境先在版本上对齐很多人打开构建面板就急着选平台、填路径结果一连串诡异报错。其实 Creator 3.x 的安卓打包是“一套工具链协作”的过程Cocos Creator 负责把游戏资源、脚本封装成原生工程Android Studio/Gradle 负责编译成 APK。两个环节各自依赖 JDK、SDK、NDK版本一乱整个链路就崩。1.1 JDK不是装个最新版就能跑3.8.7 对 JDK 的要求是JDK 17。如果你电脑上还留着 Android Studio 老项目用的 JDK 8或者图新鲜装了 JDK 21构建时大概率会看到类似“Unsupported class file major version”或“Java toolchain version not supported”的报错。重点说下为什么不能随便“装个新版”Gradle 和 Android Gradle PluginAGP对 JDK 版本是有上下限的Creator 构建时自动生成的 Gradle 工程通常会绑定一个经过验证的 Gradle 版本这套 Gradle 在 JDK 17 上跑得最稳。JDK 8 太老支撑不了新 AGP 的编译特性JDK 21 太新部分插件可能还没适配。所以我现在的固定做法是在 Android Studio 里检查内置的 JBRJetBrains Runtime版本它一般就是 17。没有 Android Studio 的话直接去 OpenJDK 官网下载 JDK 17 的 Windows/macOS 安装包。在系统环境变量里新增JAVA_HOME指向 JDK 17 的安装目录然后java -version确认输出是 17。如果你电脑上还装了多个 Java 版本建议在命令行里先用where javaWindows或which javamacOS/Linux确认当前默认 Java 是不是 17。很多隐藏问题根本不是 Cocos 配置错了而是默认 Java 被别的软件改到了其他版本。1.2 SDK 和 NDK构建面板里的版本提示要当真3.8.7 的构建面板里有“Android SDK 路径”和“NDK 路径”两栏。版本这块我直接给一份经过实测的参考组合组件推荐版本说明Android SDK PlatformAPI 34 或 35低了会有编译警告高了可能踩到新平台限制Build Tools34.0.0 或更高默认够用不用追最新NDKr21e 或 r23用构建面板自动提示的版本最省事CMake3.22.1 或 3.24仅用到原生库时才需要特殊注意这里有个容易被忽略的点Cocos Creator 3.8.7 构建时会自动告诉你“当前项目推荐使用哪个 NDK 版本”。如果你在面板里看到提示直接按提示来别自己翻旧教程。我见过有人死守 2.x 时代的 NDK r17结果 3.8.7 编译原生层时各种符号找不到。安装方式上Android Studio 的 SDK Manager 里可以直接勾选对应版本的 SDK Platform、Build Tools、NDK 和 CMake。装完以后SDK 路径通常是用户目录/AppData/Local/Android/SdkWindows或~/Library/Android/sdkmacOS。NDK 则在这个目录的ndk子目录下。1.3 Gradle 与依赖源打通下载通道才算配好Cocos Creator 构建时会给你生成一个完整的 Android 原生工程里面自带 Gradle Wrapper。正常情况下你不需要手动装 Gradle但Gradle 首次同步时会从services.gradle.org和 Google Maven 仓库下载大量依赖。如果你的网络访问这些仓库不稳定后面就是“同步半小时、转圈一整天”。我的建议是在生成原生工程后立刻去改两个文件gradle/wrapper/gradle-wrapper.properties里的distributionUrl把下载地址替换成国内可访问的镜像仓库。工程根目录build.gradle里的repositories把google()、mavenCentral()基础上加上阿里云或腾讯云的 Maven 镜像地址。这一步不是必须的但绝大多数人卡在 Gradle 环节都跟网络有关。换句话说版本对齐不只是“装对 JDK”还包括让工具链要用的依赖能顺利下载到位。2. 构建面板里的每一栏我帮你翻译成人话版本环境配好之后真正打开构建面板里面其实没几项需要反复纠结。但每一项背后的含义文档里都写得有点绕。我按自己的理解逐项拆一下。2.1 包名与应用ID开发和上架包分开用这里的“包名”填写的是 Android 的应用 ID一般用反向域名格式比如com.yourcompany.yourgame。它和你在 Cocos 里配的 Bundle ID 不一定非要不要一致但 iOS 和 Android 最好保持同一套方便统计和多端统一。实际开发中比较推荐“双包策略”测试包用一个带.debug后缀的包名上架包用正式包名。打包工具大多都允许同时存在多个签名包这样测试环境和正式环境数据隔离不会出现测试账密污染线上数据的问题。构建面板里的包名后续很难改尤其是出过包之后平台审核、微信登录回调、推送配置全跟它绑定所以第一行务必想清楚再填。2.2 密钥文件命令生成一次能用的 keystore构建面板里需要选择密钥文件.keystore 或 .jks并填写storePassword、keyAlias、keyPassword。很多新手在这里直接用 Android Studio 的“Generate Signed Bundle/APK”向导生成密钥其实命令行更直观。打开终端在 JDK 17 的bin目录下执行或确保keytool已加入 PATHkeytool -genkeypair -v -keystore release.keystore -alias mygame -keyalg RSA -keysize 2048 -validity 10000 -storepass 123456 -keypass 123456 -dname CNMyGame, OUDev, OCompany, LCity, STState, CCN执行完会生成一个release.keystore文件。后面的-validity 10000表示有效天数约 27 年避免过一段时间就过期。这个文件一定要放好并且和密码一起交给团队内专人保管别塞进 Git 仓库。一旦丢失后期只能换包名重新上架。2.3 ABI与API Level直接决定安装包大小和兼容面构建面板里“API Level”一般有min API和target APIABI 有armeabi-v7a、arm64-v8a、x86_64。我给的默认建议是minSdkVersion: 23 或 24。3.x 引擎对低版本系统支持已经弱化再往下兼容开发成本高、收益小。国内安卓设备现在的系统版本普遍在 Android 10 以上min 23 覆盖度已经足够。targetSdkVersion: 跟着商店要求走。国内应用商店目前比较常见要求 API 31 以上Google Play 的新政策要求 API 34 或更高。按你实际上架渠道来定。ABI 只勾 arm64-v8a如果只面向主流真机。x86_64 只在模拟器上有用armeabi-v7a 是 32 位兼容老旧设备才需要。只勾 arm64 能让包体直接缩小一大截。有人会担心“我只勾 arm64那老手机怎么办”现实中现在 32 位设备份额已经非常低与其照顾老设备不如把安装包体积和启动性能做好。如果真需要兼容后面再出多 ABI 包也不迟。2.4 渲染后端与引擎模块和“能跑”没关系的选项先不动构建面板里的“渲染后端”一般有OpenGL ES 3.0、OpenGL ES 2.0和Vulkan可选。默认 GLES 3.0 是兼容性和性能最稳的选择如果游戏面向高端机型、需要更高级特效再测试 Vulkan但记得构建面装确认目标真机支持。对新手来说先保持默认就好。“引擎模块”选项则是让你裁剪掉不需要的引擎功能比如不用的物理系统、音频解码格式、3D 粒子等。裁剪得越多so 和 Java 层代码就越小包体越小。但有个大前提你不能光凭感觉去裁剪最好等游戏基础功能全部实现、稳定上线后再逐步关掉根本不用的模块然后反复回归测试。否则贸然关掉某个模块结果某个 UI 动画依赖了它运行时就等着看黑屏报错。3. 构建完成只是上半场原生工程还有一堆事Cocos Creator 点完构建后会在项目的build/android目录下生成一个完整的原生 Android 工程。很多人误以为到这里 APK 就出来了其实这只是把“半成品”交给你。后续还得在 Android Studio 里走一遍 Gradle 编译、签名、打包。3.1 用Android Studio打开项目先让它自己把依赖跑完用 Android Studio 打开build/android目录首次打开会自动触发 Gradle Sync。这个过程本质上是读取工程里的 Gradle 配置去远程仓库下载 AGP、Kotlin、AndroidX 等依赖。依赖越多首次同步越慢。这时候你要做的不是点“运行”按钮而是先盯着右下角的 Sync 进度条看到 “Gradle Sync Finished” 才算过了第一关。如果中途报错去File Project Structure SDK Location确认 SDK 路径再去看local.properties文件里sdk.dir是否指向正确目录。同步完成后我习惯先执行一次Build Clean Project把缓存的 R 类、BuildConfig 清掉再做一次Build Rebuild Project。这一步能提前暴露很多资源引用、命名冲突的问题而不是等到真机安装后闪退才发现。3.2 出包方式AS图形界面与gradlew命令行在 Android Studio 里出签名包的常规路径是Build Generate Signed Bundle or APK选APK指定release.keystore填好别名和密码最后选输出目录。这种方式简单直观适合偶尔打一次包。但如果要持续集成、频繁出包我更推荐直接用 gradlew 命令行cd build/android ./gradlew assembleReleaseassembleRelease会在build/android/app/build/outputs/apk/release/下生成签名后的 APK。如果你想生成 AABGoogle Play 新上架格式就执行./gradlew bundleRelease命令行的好处是参数可重复、日志可控、可接入自动化脚本。第一次用命令行出包前先把~/.gradle/gradle.properties里加上内存参数org.gradle.jvmargs-Xmx4096m -Dfile.encodingUTF-8 android.useAndroidXtrue游戏工程依赖多内存给足能明显减少构建中途卡死或 OOM 概率。3.3 测试安装与日志抓取第一次跑真机别急着点拿到 APK 后用数据线连接安卓手机开启开发者模式的 USB 调试然后执行adb install -r build/android/app/build/outputs/apk/release/app-release.apk安装成功后先在桌面点开图标确认能进入首页。如果启动就闪退别慌用 logcat 抓实时日志adb logcat -c adb logcat | findstr /i AndroidRuntime cocos sokol ActivityWindows 下findstr可以换成grepmacOS/Linux。重点关注两行FATAL EXCEPTION和Process: 包名后面会直接告诉你崩溃的堆栈位置。4. 我从报错到出包的完整排查记录这部分是我实际踩过的坑每个我都按“现象 → 排查思路 → 最终解决”的顺序写能复现思路比抄答案更重要。4.1 报错一SDK Location无法解析现象很直接构建或 Gradle Sync 时报SDK location not found或者SDK path is not valid。我当时第一反应是去构建面板看 SDK 路径死活找不到问题所在。排查链路打开工程根目录的local.properties检查sdk.dir是不是被改成了不存在的路径。确认Cocos Creator 构建面板里填的 SDK 路径和Android Studio 里 SDK Manager 显示的路径是否一致。看 SDK 目录里有没有platforms和build-tools子目录。如果没有说明 SDK 装得不完整需要回 Android Studio 的 SDK Manager 补装。最后发现原因构建面板里的 SDK 路径指向了 Android Studio 的安装目录而真正的 SDK 在AppData/Local/Android/Sdk。这俩在旧版本 Android Studio 里差不多在新版本里已经拆开了。改成正确定路径后问题消失。4.2 报错二Gradle同步一直转圈现象新建工程后第一次 Sync进度条卡在Downloading gradle-x.x.x-all.zip或者 maven 依赖步骤转十几分钟不动。排查链路打开gradle/wrapper/gradle-wrapper.properties看distributionUrl指向哪个域名。如果是services.gradle.org这种直连地址网络稍差就很容易卡。打开build.gradle根工程文件看repositories里的仓库地址。如果只有google()和mavenCentral()自动下载时极易超时。临时区分是下载卡住还是同步卡住用浏览器手动访问distributionUrl的地址能秒开说明网络还行打不开就说明要换镜像源。最终解决把distributionUrl替换成国内可访问的 Gradle 发行包镜像地址同时repositories加上 Maven 镜像地址。改完重启 Sync全程几分钟内完成。后来我本地保留了 Gradle 发行包的离线缓存新工程直接把distributionUrl改成file:///D:/gradle/gradle-8.x-all.zip这种本地路径省掉所有下载等待。4.3 报错三CMake/ndk-build在取舍CPU架构时失败我在 3.8.7 里保留armeabi-v7a和arm64-v8a两个 ABI结果构建时候报Could not determine the dependencies of task :app:externalNativeBuild...或No toolchain found for ABI armeabi-v7a。排查链路先确认 NDK 目录里有没有对应 ABI 的 toolchain。32 位 ABI 需要 NDK 里包含arm-linux-androideabi-*工具链部分精简版 NDK 可能只带了 arm64。确认 NDK 版本和 AGP 要求的 NDK 版本是否兼容。AGP 在新版本里经常对 NDK 版本做了约束版本不匹配就会出现“明明装了 NDK 却说找不到”的假象。如果项目同时依赖外部原生库.so还要检查app/src/main/jniLibs里是否包含对应 ABI 目录缺了哪个 ABI 目录就可能触发这类错误。我的方案是把 ABI 统一收敛到arm64-v8a一个。游戏没有涉及老设备兼容需求省掉 32 位工具链后构建时间直接缩短三分之一包体也小了。如果团队里有测试机还是 32 位再单独补一个armeabi-v7a包不要同时塞在一个包里做动态适配。4.4 报错四APK装上后一启动就闪退这个坑最让人崩溃构建、签名全成功APK 也装进手机了结果点击图标闪一下就退回桌面。抓日志adb logcat | grep AndroidRuntime看到关键行FATAL EXCEPTION: main java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader couldnt find libcocos.so这个报错的意思是 so 库没有正确打进去。排查链路打开build/android/app/build/outputs/apk/release/用压缩软件打开 APK查看lib/目录里是否包含arm64-v8a/libcocos.so。如果没有说明构建时原生库没参与打包。去 Android Studio 检查app/build.gradle里的sourceSets配置看jniLibs.srcDirs是否被误改。如果 so 存在但仍然崩溃再看targetSdkVersion。有些高版本系统对 32 位 so 加载有严格限制只适用于 64 位包却有 32 位引用也会导致加载失败。我那次的原因比较低级为了压缩 APK 体积手动在 Gradle 里加了ndk.abiFilters arm64-v8a但引擎原生构建产物里也做了类似过滤两边组合起来反而把 so 过滤没了。删掉重复配置保留构建面板的 ABI 选择问题解决。5. 正式包之外的几个优化选项配置跑通、APK 能装、能玩这只是及格线。真到提测和上架阶段还有几件事值得在这一版就做掉。5.1 拆ABI和资源压缩把包体降下来游戏包体是硬指标。建议构建时直接勾选按 ABI 分包如果面板支持或者出包后用 Android Studio 的 APK Analyzer 看看包体构成。通常大头是assets目录里的游戏资源图片、音频、图集lib/arm64-v8a下的引擎 sores里的启动图、图标、多密度资源图片资源尽量在导入 Cocos 时就开启压缩纹理构建时勾选纹理压缩选项。音频格式也尽量用压缩率更高的.m4a或.ogg别直接塞无损 WAV。这部分不用等到打包阶段再优化项目初期做好资源规范后面包体自然小。5.2 命令行构建改配置前先固化一个脚本手动在构建面板点一遍流程太慢而且容易漏参数。我后来把打包命令固化成了一个脚本大概长这样cocos --project . --build platformandroid;debugfalse;md5Cachetrue;buildPathbuild cd build/android ./gradlew assembleReleasecocos命令是构建工具自带的 CLI执行前确保你已经跑过一次图形化构建让工程配置有地方落盘。脚本化之后每次改完代码只需要跑两条命令就能出新包不必再打开整个编辑器。后续想接 CI也只要把这两条命令扔到流水线里就行。5.3 引擎裁剪和热更新目录规划关于引擎模块裁剪我前面说过要等稳定后再做。这里补充一个和安卓打包强相关的点如果项目用了热更新机制资源目录规划必须在第一次打包时就定好。Cocos Creator 3.8 的 Asset Bundle 可以打到远程服务器也可以内置到包体。打包配置里有些 Bundle 要勾选“不参与主包”或“远程包”这些标记直接影响安卓包里的assets结构。我踩过的一个后续问题是第一次打包时把所有 Bundle 都塞进了主包后来想拆远程包改配置后旧客户端升级逻辑变得很别扭因为资源引用路径变了旧版本不能平滑切换到新资源结构。所以第一次打包前先把哪些 Bundle 内置、哪些走远程规划清楚。原生包只要生成一次中途大改资源结构坑的不是引擎是你自己。最后分享一个小习惯每次在构建面板动任何参数前先把旧的build/android目录备份一下或者干脆删掉重新构建。3.8.7 的增量构建有时会残留旧配置导致“改了参数但没生效”的假象。全量构建虽然慢但每次都是干净环境排查问题会省心很多。另外出完包先跑一版空场景测试原生工程是否正常再往里面加业务代码报错串在一起时真的很难分辨是引擎配置问题还是自己代码问题。