第二章：安卓端启动流程详解与疑难杂症调试手册

想让一个安卓项目跑起来，从表面看无非就是：双击打开、连接真机、点击运行。

但是到了互动娱乐组件项目里，事情就变成了：点击运行→等待→黑屏→白屏→强制退出→LogCat爆炸→你怀疑人生。

本章就来系统性解决几个问题：

• cocos2d-js 安卓项目的完整启动链路分析

• 构建时常见报错的底层机制解释

• 安卓平台加载资源失败的调试流程

• main.js 到 GameMain 场景的启动过程全解析

---

一、环境搭建准备（非常重要）

你如果使用 cocos2d-js 开发安卓端，99%的问题都来自环境不匹配。

✅ 推荐环境版本

项目	推荐版本
Cocos2d-js	v3.17.2（稳定）
NDK	r16b
Android SDK	API 29 或以上
Java	JDK 1.8
Node.js	v14 LTS
VS（可选）	Visual Studio 2017（勾选C++组件）

✅ 环境变量配置（Windows）

# 添加以下变量到系统环境中
ANDROID_SDK_ROOT=C:\Android\Sdk
NDK_ROOT=C:\Android\Sdk\ndk\16.1.4479499
JAVA_HOME=C:\Program Files\Java\jdk1.8.0_211
COCOS_CONSOLE_ROOT=D:\Cocos\cocos2d-x-3.17.2\tools\cocos2d-console\bin

注意：路径不要有中文！路径不要有中文！路径不要有中文！（重要的事情说三遍）

---

二、项目初始化流程剖析（main.js 到大厅）

以这个项目为例，启动过程大致如下：

main.js
└── new cc.App()
     └── app.start()
          └── 进入 SplashScene（启动页）
               └── 加载资源包 manifest
                    └── 预加载场景资源（大厅）
                         └── 进入主场景

这是典型的游戏引擎加载模式，属于懒加载机制（Load on Demand）。下面是主文件 main.js 示例：

require("src/settings.js");
require("src/cocos2d-jsb.js");
require("jsb-adapter/jsb-engine.js");

cc.game.run({
    id: 'GameCanvas',
    debugMode: cc.debug.DebugMode.INFO,
    showFPS: true,
    frameRate: 60,
    scenes: ["SplashScene"]
});

其中 settings.js 是打包后由构建工具生成的启动配置。

当你点击运行时，引擎会加载 project.json 里的场景路径，逐步进入主界面。

常见问题 Q&A：

• 黑屏但Log无报错？

  • 检查是否缺失 SplashScene.fire 或其绑定资源。

• 提示找不到资源路径？

  • 看 settings.js 是否正确记录资源路径，注意大小写敏感。

• 进入主场景但无 UI？

  • 多半是 UI 层 prefab 没加载成功，看看你 UIManager 是否绑定了默认层级。

---

三、资源加载失败排查实录

80%的黑屏、白屏、闪退都和资源加载失败有关。

cc.loader.loadRes("gameModules/Module1/prefab/GameMain", cc.Prefab, function (err, prefab) {
    if (err) {
        cc.error("加载失败", err);
        return;
    }
    let node = cc.instantiate(prefab);
    cc.director.getScene().addChild(node);
});

如果你在 LogCat 中看到如下错误：

Error: Asset url is not found: gameModules/Module1/prefab/GameMain

请按以下方式排查：

1. prefab 路径大小写是否与物理目录一致（Win不区分，安卓区分）

2. prefab 是否已经打包进资源目录 import/ 下

3. 是否被 cc.loader.setAutoRelease() 提前释放了？

4. 动态加载是否放在未加载资源包时触发？

---

四、构建打包中的常见报错及处理

1. Build Failed: xxx.gradle could not find method compile()

原因： gradle 版本不兼容 compile() 已被废弃

解决： 打开 proj.android-studio/app/build.gradle 修改为：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.android.support:appcompat-v7:28.0.0'
}

2. NDK not configured.

原因： NDK 路径未设置或版本不对

解决： 在 local.properties 添加：

ndk.dir=C:\Android\Sdk\ndk\16.1.4479499

3. java.lang.UnsupportedClassVersionError

原因： 编译器用的是 JDK 1.8 以上，但项目使用了老版 Gradle 插件

解决方式： 要么换 JDK 1.8，要么升级 Gradle 插件

classpath 'com.android.tools.build:gradle:3.5.0'

---

五、安卓真机调试常用技巧

日志查看命令（LogCat）

adb logcat -s jsb cocos2d

过滤关键报错关键词：

adb logcat | findstr "jsb exception error native"

热更新失败调试：

if (jsb.fileUtils.isFileExist(updatePath)) {
    // 热更新文件存在
    hotUpdateManager.load(updatePath);
} else {
    console.warn("热更新路径不存在，使用默认资源启动");
    cc.director.loadScene("HallScene");
}

---

小结：跑得动 ≠ 稳得住

很多人以为跑起来就完事了，其实刚开始。调试才是你修炼的开端。

我们在本章中完整梳理了：

• 启动流程的调用链

• 构建时常见错误及处理方案

• 资源加载失败的根因

• 日志调试与环境排错技巧