一、 环境准备与 CLI 安装

在创建项目前，需确保本地已安装 Node.js（建议 16.x 或以上版本），并配置好 Java 环境（建议 JDK 11.0.2 以上）。随后，需要全局安装 ArkUI-X 的命令行工具 ACE Tools。

安装命令：

# 1. 修改 npm 源（推荐华为云源，提升下载速度）
# 在用户目录的 .npmrc 文件中添加：
# @ohos:registry=https://repo.harmonyos.com/npm/
# registry=https://repo.huaweicloud.com/repository/npm/

# 2. 全局安装 ACE 命令
npm install -g @ohos/ace-cli

二、 创建跨平台工程

安装完成后，即可使用 ace create 命令初始化项目。在执行过程中，CLI 会引导开发者依次输入工程名称、包名称（Bundle Name）、目标系统（OpenHarmony 或 HarmonyOS）以及项目类型（Application 或 Library）。

创建命令：

# 执行创建命令
ace create project

# 交互式输入示例：
# ? Please enter the project name: MyCrossApp
# ? Please enter the bundle name (com.example.MyCrossApp): com.example.mycrossapp
# ? Please enter the system (1: OpenHarmony, 2: HarmonyOS): 1
# ? Please enter the project type (1: Application, 2: Library): 1
# ? Please enter the template (1: Empty Ability, 2: Native C++): 1

三、 工程目录结构解析

项目创建成功后，会生成一套标准化的跨平台工程目录。核心业务代码位于 entry 目录下，各平台的原生代码则被隔离在各自的文件夹中。

目录结构示例：

MyCrossApp/
├── entry/                 # 主业务模块（ArkTS 代码）
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/       # ArkTS 声明式 UI 与业务逻辑
│   │   │   ├── resources/ # 跨平台资源文件
│   │   │   └── module.json5 # 模块配置
│   └── build-profile.json5 # 构建配置
├── ios/                   # iOS 平台原生代码
│   ├── AppDelegate.swift
│   └── Info.plist
├── android/               # Android 平台原生代码
└── arkui-x.config.json5   # 跨平台核心配置文件

四、 多平台构建与运行

ACE Tools 提供了统一的命令来编译和打包不同平台的安装包。开发者只需进入项目根目录，即可一键构建并安装到对应的真机或模拟器中。

构建与运行命令：

cd MyCrossApp

# 安装并运行到 Android 设备（构建 APK）
ace run apk

# 安装并运行到 iOS 设备（构建 App，需在 macOS 上并配置 Xcode）
ace run app

# 安装并运行到 OpenHarmony 设备（构建 HAP）
ace run hap

五、 多平台适配配置与依赖管理

在跨平台开发中，不同平台的最低 SDK 版本、编译参数以及依赖库往往存在差异。ArkUI-X 允许开发者在 oh-package.json5 或 build-profile.json5 中精细配置各平台的构建参数，确保工程在多端顺利编译。

核心配置示例（oh-package.json5）：

{
  "arkui-x": {
    "targets": ["android", "ios", "web"],
    "android": {
      "minSdkVersion": 21,
      "compileSdkVersion": 33
    },
    "ios": {
      "deploymentTarget": "12.0",
      "enableBitcode": false
    }
  }
}

六、 编写跨平台 UI 组件与状态管理

ArkUI-X 沿用鸿蒙 ArkUI 的组件化开发思想，开发者可以使用声明式语法构建 UI，并通过状态管理装饰器（如 @State、@ObjectLink）实现跨组件的数据同步。这些组件最终会被编译为多端统一渲染的指令。

核心代码示例（ArkTS）：

@Entry
@Component
struct Index {
  @State message: string = 'Hello ArkUI-X'
  build( ) {
    Column() {
      Text(this.message)
        .fontSize(24)
        .fontColor(Color.Blue)
      Button('Click Me')
        .onClick(() => {
          this.message = '跨平台交互成功'
        })
    }
    .width('100%')
    .height('100%')
  }
}

七、 跨平台设备能力调用与权限适配

在调用相机等原生设备能力时，ArkUI-X 提供了统一的 Kit 接口。但需要注意的是，跨平台项目必须在各个平台（HarmonyOS、Android、iOS）的配置文件中分别声明对应的权限，否则会导致调用失败。

核心代码示例（相机调用）：

import camera from '@kit.DeviceCapabilityKit'

@Entry
@Component
struct CameraPage {
  controller: camera.CameraController = new camera.CameraController()
  build( ) {
    Stack() {
      CameraPreview(this.controller)
        .width('100%')
        .height('100%')
      Button('拍照')
        .onClick(() => {
          this.controller.takePhoto()
        })
    }
  }
}

注：HarmonyOS 需在 module.json5 中声明 ohos.permission.CAMERA；Android 需在 AndroidManifest.xml 中添加对应权限声明。

八、 多平台构建、调试与性能分析

除了基础的 ace run 命令，开发者还可以使用更精细的构建指令，并结合平台特定的调试工具来排查问题。

构建与调试指令：

# 构建 Android 调试包
ace build android --mode debug

# 构建 iOS 应用（需指定 Scheme）
ace build ios --scheme YourAppScheme

# 指定设备 ID 运行调试
ace run android --device [设备ID]

在调试过程中，可以使用 @arkui-x/debug 模块输出跨平台日志，并在 DevEco Studio 中切换平台预览模式。上线前，建议通过 DevEco Profiler 分析各平台的性能差异，并定期执行 ace lint 进行代码规范检查。

  1. 优先使用声明式布局：替代传统的命令式 UI 操作，利用框架的差分更新算法保证多端性能。
  2. 样式统一管理：使用 @Styles 或媒体查询（Media Query）来统一多平台样式，并适配不同分辨率与异形屏（如使用 SafeArea 组件避开刘海屏）。
  3. 复杂逻辑原生复用：对于极度复杂的业务逻辑，建议通过 Native C++ 实现跨平台复用，以获得最佳性能。
  4. 原生能力桥接：对于 ArkUI-X 尚未内置的原生能力，通过 ArkUI-X Bridge 桥接实现，并在鸿蒙预览环境中做好 Bridge 调用的异常保护。

九、 构建工程化：多环境配置与 CI/CD 流水线

在团队协作中，硬编码的配置和手动构建是不可接受的。必须建立严格的环境隔离与自动化流程。

1. 多环境配置管理

利用 oh-package.json5 和构建脚本，实现 Dev、Test、Prod 环境的自动切换。

目录结构建议：

MyCrossApp/
├── config/
│   ├── config.dev.json5
│   ├── config.test.json5
│   └── config.prod.json5
├── scripts/
│   └── build.sh
└── entry/
    └── src/main/ets/common/Constants.ets // 动态生成的配置文件

自动化脚本逻辑（build.sh）：

#!/bin/bash
ENV=$1 # 传入参数 dev/test/prod

# 1. 复制对应环境配置到源码目录
cp ./config/config.$ENV.json5 ./entry/src/main/ets/common/Constants.ets

# 2. 执行构建
if [ "$2" == "android" ]; then
  ace build android --mode release
elif [ "$2" == "ios" ]; then
  ace build ios --scheme Release
fi
2. CI/CD 集成

在 .gitlab-ci.yml 或 GitHub Actions 中配置流水线，实现代码提交即自动打包：

stages:
  - build
  - deploy

build_android:
  stage: build
  script:
    - npm install -g @ohos/ace-cli
    - sh scripts/build.sh prod android
  artifacts:
    paths:
      - entry/build/outputs/apk/

十、 原生桥接：复杂逻辑的 C++ 跨平台复用

ArkUI-X 的 Bridge 机制虽然方便，但对于图像处理、音视频编解码等高性能场景，ArkTS 与原生通信的序列化开销过大。此时应采用 Native C++ 核心层。

架构设计：

  1. Common (C++)：存放核心算法（如加密、图像滤镜、复杂计算）。
  2. Platform Channels：各平台仅做“胶水层”，调用 C++ 库。

C++ 接口定义（shared_module/cpp/algorithm.h）：

#ifndef ALGORITHM_H
#define ALGORITHM_H

extern "C" {
    // 导出 C 接口，避免 C++ 命名修饰问题
    const char* processImageData(const char* inputJson);
}

#endif

ArkTS 调用层（使用 NAPI 封装）：

// entry/src/main/ets/native/libnative.so.d.ts
declare function processImageData(input: string): string;

@Entry
@Component
struct ImageProcessor {
  async handleImage(data: string) {
    // 直接调用底层 C++，无 JS Bridge 序列化损耗
    const result = processImageData(data);
    console.info('C++ Result:', result);
  }
}
# harmonyos # 鸿蒙系统 # 鸿蒙
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

Compose Multiplatform 三方库 Coil（coil-core）的 OpenHarmony 鸿蒙化适配实战

avatar 开源鸿蒙跨平台开发者社区
cover

otlinx-datetime 官方 KMP 日期时间库的 OpenHarmony 鸿蒙化适配实战

avatar 开源鸿蒙跨平台开发者社区
cover

开源鸿蒙平台 KMP 三方库 Essenty 适配全流程：从生命周期抽象到状态重建验证

avatar 开源鸿蒙跨平台开发者社区