Cocos 集成纯血鸿蒙 App
技术方案与集成指南
版本：v1.0 | 平台：HarmonyOS Next | 引擎：Cocos Creator 3.8.x
1. 概述
本文档描述如何将 Cocos Creator 游戏项目集成到纯血鸿蒙 App 的某个 Tab 页面中，实现原生 ArkTS 界面与 Cocos 游戏画面的混合展示，同时说明后续 Cocos 项目的迭代更新流程。
1.1 技术背景
纯血鸿蒙（HarmonyOS Next）不兼容安卓，是华为全新的操作系统生态。Cocos Creator 3.8.x 支持将游戏项目导出为 HarmonyOS Next 工程，在原生端使用 XComponent 组件承载游戏渲染画面，从而实现嵌入现有 App 的需求。
1.2 集成架构总览
图 1：纯血鸿蒙 App 集成 Cocos 架构示意
2. 环境准备
2.1 所需工具版本
|---------------|--------------------|------------|
| 工具 | 版本要求 | 用途 |
| Cocos Creator | ≥ 3.8.5（推荐 3.8.7+） | 游戏开发与构建 |
| DevEco Studio | 最新稳定版 | 鸿蒙工程编译打包 |
| HarmonyOS SDK | 与 DevEco Studio 配套 | 鸿蒙原生开发 |
| Node.js | ≥ 18.x | Cocos 构建依赖 |
2.2 Cocos Creator 环境配置
打开 Cocos Creator，依次进入「偏好设置 → 外部程序」，配置以下路径：
- HarmonyOS NDK 路径：DevEco Studio 安装目录下的 ndk/ 子目录
- HarmonyOS SDK 路径：DevEco Studio 安装目录下的 sdk/ 子目录
3. Cocos Creator 构建阶段
3.1 仓库管理建议
为了方便后续独立迭代，强烈建议将 Cocos 项目与纯血鸿蒙 App 主工程分开管理：
- Cocos 项目：独立 Git 仓库，负责游戏逻辑与资源
- 鸿蒙主工程：独立 Git 仓库，负责 App 框架与业务逻辑
- 两个仓库通过构建产物目录引用，互不耦合
3.2 构建步骤
在 Cocos Creator 中打开构建发布面板（菜单：项目 → 构建发布），按以下配置执行构建：
|-------------|-------------------------------|
| 配置项 | 推荐值 |
| 发布平台 | HarmonyOS Next |
| JS 引擎 | JSVM（性能最优，支持 JIT） |
| 构建模式 | Debug（调试）/ Release（发布） |
| 开始场景 | db://assets/scenes/main.scene |
| 包含场景 | 按需勾选，不用的场景不勾（减小包体） |
3.3 构建产物说明
构建完成后，产物位于项目目录下的 build/harmonyos-next/，主要文件结构如下：
build/harmonyos-next/
├── entry/ # 主模块（引入主工程时使用）
│ ├── src/main/cpp/ # C++ 桥接代码
│ ├── src/main/ets/ # ArkTS 入口与 XComponent
│ └── oh-package.json5 # 模块依赖配置
├── assets/ # 游戏资源（脚本、图片、音频等）
└── libs/ # libcocos.so 等原生库
4. 集成到纯血鸿蒙 App 主工程
4.1 完整集成流程
图 2：Cocos 集成纯血鸿蒙 App 完整流程
4.2 引入 Cocos 模块
用 DevEco Studio 打开纯血鸿蒙 App 主工程，在根目录的 oh-package.json5 中添加依赖：
{
"dependencies": {
"cocos-game": "file:../cocos_build/entry"
}
}
其中 ../cocos_build/entry 为 Cocos 构建产物中 entry 目录的相对路径，根据实际目录结构调整。
4.3 在 Tab 页嵌入 XComponent
在纯血鸿蒙 App 的游戏 Tab 对应的 ArkTS 文件中，引入并使用 XComponent 组件：
import { XComponentType } from '@ohos.arkui.component'
@Entry
@Component
struct GameTabPage {
build() {
Column() {
// 嵌入 Cocos 游戏画面
XComponent({
id: 'cocosGame',
type: XComponentType.SURFACE,
libraryname: 'cocos' // 对应 libcocos.so
})
.width('100%')
.height(400) // 按设计稿调整高度
}
}
}
4.4 JS 与 ArkTS 通信（可选）
如果 Cocos 游戏需要与 App 交换数据（如传入用户 Token、单词数据等），使用反射机制：
ArkTS 侧：暴露静态方法
export class AppBridge {
static getUserToken(): string {
return globalThis.userToken ?? ''
}
static onGameEvent(eventName: string, data: string): void {
// 处理来自 Cocos 的事件
console.log('Game event:', eventName, data)
}
}
Cocos JS 侧：调用 ArkTS 方法
// 调用 ArkTS 静态方法获取数据
const token = jsb.reflection.callStaticMethod(
'com.yourapp.AppBridge',
'getUserToken',
'()Ljava/lang/String;'
)
5. 签名配置与真机调试
5.1 配置自动签名
在 DevEco Studio 中，进入 File → Project Structure → Signing Configs，按以下步骤操作：
- 登录华为开发者账号
- 勾选「Automatically generate signature」
- 选择对应的 Bundle Name（包名需与主工程一致）
- 点击 Apply → OK 保存
注意：自动签名证书可能定期更新，若安装失败，先卸载设备上的旧版 App，再重新安装。
5.2 真机运行
鸿蒙 Next 模拟器当前不支持 GPU 加速，Cocos 游戏必须在真机上运行和调试。步骤如下：
- 用数据线连接 HarmonyOS Next 手机，开启「开发者模式」和「USB 调试」
- 在 DevEco Studio 顶部工具栏选择目标设备
- 点击运行（▶）按钮，等待编译安装
- 如安装失败，检查签名配置或卸载旧包重试
6. 后续迭代更新流程
集成完成后，Cocos 项目的日常迭代更新遵循以下简单流程，无需改动主工程 ArkTS 代码：
图 3：Cocos 迭代更新流程
6.1 具体步骤
- 步骤 1：在 Cocos Creator 中完成游戏内容修改
- 步骤 2：重新执行构建，生成新的 build/harmonyos-next/ 产物
- 步骤 3：将新产物中的 assets/ 目录和 libcocos.so 覆盖到主工程对应路径
- 步骤 4：在 DevEco Studio 中重新 Build APP，无需修改任何 ArkTS 代码
6.2 建议的 CI/CD 自动化
如果团队有 CI/CD 基础，可以编写脚本实现自动化同步：
#!/bin/bash
1. Cocos 构建
cocos build --platform harmonyos-next --mode release
2. 同步产物到主工程
cp -r build/harmonyos-next/assets ../main_app/cocos_module/
cp -r build/harmonyos-next/libs ../main_app/cocos_module/
7. 打包与发布
7.1 生成 .app 安装包
在 DevEco Studio 中执行菜单：Build → Build Hap(s)/APP(s) → Build APP(s)，等待编译完成后，在 build/outputs/default/ 目录下生成 .app 文件。
7.2 上传 AppGallery
- 登录 AppGallery Connect（https://developer.huawei.com/）
- 创建应用或进入现有应用
- 在「版本信息」中上传 .app 文件
- 填写版本说明，提交审核
8. 常见问题
|-------------|----------------------------------------|
| 问题 | 解决方案 |
| 安装失败 / 签名错误 | 卸载旧版 App，重新配置自动签名后安装 |
| 游戏画面空白 / 黑屏 | 确认 libraryname 与 so 文件名一致，检查 assets 路径 |
| 模拟器无法运行 | Cocos 游戏必须真机调试，模拟器不支持 GPU 加速 |
| JS 引擎选哪个 | 选 JSVM，鸿蒙系统为其开放 JIT，性能最优 |
| 包体过大 | 构建时只勾选用到的场景，并开启资源压缩 |