1. 项目概述
最近在帮团队升级Cocos Creator 3.8.7的安卓打包环境时,发现官方文档虽然提供了基础指引,但很多实际开发中会遇到的关键配置细节和坑点都没有明确说明。作为一个踩过无数打包坑的老司机,今天就把完整的安卓打包配置流程和避坑指南整理出来,特别适合正在从Cocos Creator 2.x迁移到3.x的团队参考。
2. 环境准备
2.1 JDK安装与配置
Android Studio 2022.3.1(代号"Flamingo")开始强制要求JDK17,但Cocos Creator 3.8.7的编译脚本对JDK版本有特殊要求:
bash复制# 查看当前JDK版本
java -version
建议安装Azul Zulu JDK 11(LTS版本),这是经过Cocos官方测试的稳定版本。安装后需要配置环境变量:
- 新建系统变量
JAVA_HOME指向JDK安装路径(如C:\Program Files\Zulu\zulu-11) - 在Path中添加
%JAVA_HOME%\bin
注意:如果电脑上同时存在多个JDK版本,建议在Android Studio的
File > Project Structure中显式指定JDK位置,避免Gradle构建时版本冲突。
2.2 Android Studio配置
安装Android Studio时务必勾选以下组件:
- Android SDK (API级别至少包含API 28)
- Android SDK Platform-Tools
- Android SDK Build-Tools (推荐30.0.3)
- NDK (版本21.4.7075529)
安装完成后需要配置SDK路径:
- 在Cocos Creator中打开
项目 > 项目设置 > 原生开发环境 - 设置Android SDK路径(如
C:\Users\[用户名]\AppData\Local\Android\Sdk) - 设置NDK路径(如
C:\Users\[用户名]\AppData\Local\Android\Sdk\ndk\21.4.7075529)
3. 项目配置详解
3.1 build.gradle关键参数
打开项目目录/build/android/build.gradle,重点关注这些配置项:
groovy复制android {
defaultConfig {
applicationId "com.yourcompany.game" // 必须与AndroidManifest.xml一致
minSdkVersion 21 // 最低支持Android 5.0
targetSdkVersion 33 // 建议与compileSdkVersion一致
versionCode 1 // 整数,每次发布递增
versionName "1.0.0" // 用户可见版本号
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a' // 按需添加x86等架构
}
}
signingConfigs {
release {
storeFile file('keystore/release.keystore')
storePassword 'yourpassword'
keyAlias 'youralias'
keyPassword 'yourpassword'
}
}
}
避坑提示:如果遇到
Could not determine the dependencies of task ':app:lintVitalRelease'错误,在android块内添加lintOptions { checkReleaseBuilds false }
3.2 AndroidManifest.xml定制
位于项目目录/build/android/app/src/main/AndroidManifest.xml,常用修改包括:
xml复制<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application
android:icon="@mipmap/icon"
android:label="@string/app_name"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
android:hardwareAccelerated="true"
android:requestLegacyExternalStorage="true"> <!-- 适配Android 10+存储权限 -->
<meta-data
android:name="unityplayer.SkipPermissionsDialog"
android:value="true" /> <!-- 跳过Unity默认权限弹窗 -->
</application>
</manifest>
4. 打包流程实操
4.1 构建面板配置
在Cocos Creator编辑器中选择项目 > 构建发布,安卓平台关键配置:
- 包名:必须与build.gradle中的applicationId完全一致(如com.company.game)
- 目标平台:根据需求选择ARMv7或ARM64(建议同时勾选)
- 模板:选择
default或link(后者支持动态库分离) - 加密脚本:勾选后会增加包体解析时间
经验之谈:首次构建前建议先执行
项目 > 清理项目,避免缓存导致的奇怪问题
4.2 生成APK后的处理
构建完成后在项目目录/build/android下会生成完整的Android工程,此时有两种选择:
-
直接生成APK:
- 命令行进入该目录执行
gradlew assembleRelease - 产出路径:
app/build/outputs/apk/release/app-release.apk
- 命令行进入该目录执行
-
导入Android Studio调试:
- 用Android Studio打开
build/android目录 - 建议先执行
File > Sync Project with Gradle Files - 可通过
Run > Edit Configurations添加logcat过滤器
- 用Android Studio打开
5. 常见问题排查
5.1 构建时报错处理
问题1:Failed to apply plugin 'com.android.internal.version-check'
- 原因:Gradle插件版本不兼容
- 解决:修改
项目目录/build/android/build.gradle中的classpath:groovy复制dependencies { classpath 'com.android.tools.build:gradle:4.2.2' // 推荐版本 }
问题2:NDK not configured
- 检查NDK路径是否包含空格或中文
- 在
local.properties中添加明确路径:properties复制ndk.dir=C\:\\path\\to\\ndk\\21.4.7075529 sdk.dir=C\:\\path\\to\\sdk
5.2 运行时崩溃分析
黑屏闪退:
- 检查
adb logcat输出,常见原因包括:- 缺少SO库(检查abiFilters配置)
- OpenGL ES版本不匹配(在main.cpp中修改GLContextAttrs)
- 在Android Studio的Run/Debug配置中添加环境变量:
code复制COCOS_CONSOLE_LOG=1 # 启用Cocos原生日志
纹理加载失败:
- 确认资源文件已正确打包到APK的assets目录
- 检查图片格式是否支持(PVRTC需要特定扩展)
6. 性能优化技巧
6.1 包体瘦身方案
-
纹理压缩:
- 在
项目设置 > 功能裁剪中启用ASTC/PVRTC - 使用TexturePacker生成合图时选择对应格式
- 在
-
代码裁剪:
groovy复制android { buildTypes { release { minifyEnabled true proguardFiles 'proguard-rules.pro' } } } -
动态库分离:
- 构建时选择
link模板 - 将so库上传到CDN,运行时下载
- 构建时选择
6.2 启动速度优化
-
修改
proj.android/app/src/main/AndroidManifest.xml:xml复制<activity android:name="org.cocos2dx.javascript.AppActivity" android:screenOrientation="landscape" android:configChanges="orientation|keyboardHidden|screenSize" android:launchMode="singleTask" android:theme="@android:style/Theme.NoTitleBar.Fullscreen"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> -
在AppActivity.java中预加载资源:
java复制@Override protected void onCreate(Bundle savedInstanceState) { getWindow().setBackgroundDrawable(null); // 避免默认背景闪烁 super.onCreate(savedInstanceState); // 初始化广告SDK等第三方库 }
7. 持续集成方案
7.1 Jenkins自动化打包
创建Jenkins任务时建议使用以下构建脚本:
groovy复制pipeline {
agent any
stages {
stage('Checkout') {
steps {
git 'https://your-repo-url.git'
}
}
stage('Build') {
steps {
bat '''
cd /d "%WORKSPACE%"
CocosCreator.exe --path . --build "platform=android"
cd build/android
gradlew assembleRelease
'''
}
}
stage('Deploy') {
steps {
archiveArtifacts artifacts: 'build/android/app/build/outputs/apk/**/*.apk'
}
}
}
}
7.2 版本号自动递增
在build.gradle中添加自动递增逻辑:
groovy复制def getVersionCode = { ->
def code = (System.getenv("BUILD_NUMBER") ?: "1").toInteger()
return code
}
android {
defaultConfig {
versionCode getVersionCode()
}
}
8. 扩展功能集成
8.1 接入Firebase
- 将
google-services.json放入app模块目录 - 修改build.gradle:
groovy复制dependencies { implementation platform('com.google.firebase:firebase-bom:32.0.0') implementation 'com.google.firebase:firebase-analytics' } apply plugin: 'com.google.gms.google-services'
8.2 深度链接配置
在AndroidManifest.xml中添加intent-filter:
xml复制<activity android:name="org.cocos2dx.javascript.AppActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="yourgame" android:host="open" />
</intent-filter>
</activity>
在JavaScript中通过cc.sys.getLaunchOptions()获取参数