如何在MacOS 上使用 Flutter 构建鸿蒙App

根据 HDC 最新数据，鸿蒙生态的设备数量目前已超过 7 亿，已有 220 万 HarmonyOS 开发者投入到鸿蒙世界的开发中，API 日调用 590 亿次，软硬件产品超过 350 款。目前各大厂商纷纷与华为合作构建鸿蒙版移动应用，华为内部也主导适配目前的主流跨平台方案Flutter，并提供反向适配支持，此文将分享如何在Mac上构建鸿蒙App。

一、Harmony Flutter

目前社区最新支持 Flutter 3.7.12 OpenHarmony-SIG/flutter_flutter (gitee.com)

二、Node 环境配置

1、Node 管理工具 nvm

• nvm: github.com/nvm-sh/nvm

2、安装 nvm

i): 下载并安装

curl -o- raw.githubusercontent.com/nvm-sh/nvm/... | bash

ii): 添加环境变量到 ~/.zshrc

# nvm
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

3、使用 nvm 管理 node

i): 安装 node nvm install

$ nvm install 16
Now using node v16.9.1 (npm v7.21.1)

ii): 切换 node 版本 nvm use

$ nvm use 16  
Now using node v16.9.1 (npm v7.21.1)

iii): 查看 node 版本 nvm -v

$ node -v 
v16.9.1

4、在用户目录 /User/xxx/ 创建 .npmrc 文件，配置如下

registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

三、Java 环境配置

1、安装和查看本地 java 版本及 jdk 路径

a) 安装Java11 和 Java 17

• 鸿蒙签名工具基于 Gradle 7.1 编译构建（需要jdk11）

• ohsdkmgr 必须jdk17+

  $b\; r\; e\; w\; i\; n\; s\; t\; a\; l\; l\; o\; p\; e\; n\; j\; d\; k\; @\; 11\; brew\; install\; openjdk@11$brewinstallopenjdk@11 brew install openjdk@17

b) 查看 java 路径 /usr/libexec/java_home -V

 $ /usr/libexec/java_home -V
 
 Matching Java Virtual Machines (3):
    17.0.9 (x86_64) "Homebrew" - "OpenJDK 17.0.9" /usr/local/Cellar/openjdk@17/17.0.9/libexec/openjdk.jdk/Contents/Home
    11.0.21 (x86_64) "Homebrew" - "OpenJDK 11.0.21" /usr/local/Cellar/openjdk@11/11.0.21/libexec/openjdk.jdk/Contents/Home
    1.8.391.13 (x86_64) "Oracle Corporation" - "Java" /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home
/usr/local/Cellar/openjdk@17/17.0.9/libexec/openjdk.jdk/Contents/Home

2、Java版本管理工具

a) 安装 jenv brew install jenv

b) 添加环境变量 ~/.zshrc

export PATH="$HOME/.jenv/bin:$PATH" 
eval "$(jenv init -)" 

c) 添加 jdk 到 jenv jenv add

 jenv add /usr/local/Cellar/openjdk@17/17.0.9/libexec/openjdk.jdk/Contents/Home

d) 查看 jenv 管理的 jdk 版本 jenv versions

$ jenv versions
    
  system
  1.8.0.391
  11.0
  11.0.21
  17.0
* 17.0.9 (set by /Users/xxx/.jenv/version)
  openjdk64-11.0.21
  openjdk64-17.0.9
  oracle64-1.8.0.391

e) 切换 jdk 版本 jenv global

$ jenv global 11.0.21

f) 查看当前使用 java 版本 java -version

openjdk version "17.0.9" 2023-10-17
OpenJDK Runtime Environment Homebrew (build 17.0.9+0)
OpenJDK 64-Bit Server VM Homebrew (build 17.0.9+0, mixed mode, sharing)

3、Gradle 配置

i): 下载 gradle7.1: https://gradle.org/releases/

ii): 添加 gradle 环境变量

export PATH=/Users/xxx/ohos/tools/gradle-7.1/bin:$PATH

四、同步引擎代码

1、文件夹目录分布结构如下

2、下载 depot_tools

$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

3、设置环境变量：

export PATH=/Users/xxx/ohos/flutter/depot_tools:$PATH

4、创建 engine 目录，创建文件 .gclient并添加以下代码

solutions = [
  {
    "managed": False,
    "name": "src/flutter",
    "url": "git@gitee.com:openharmony-sig/flutter_engine.git",
    "custom_deps": {},
    "deps_file": "DEPS",
    "safesync_url": "",
  },
]

5、切换到 engine 目录，执行gclient sync执行完成如下

五、Harmony SDK 配置

1、Command Line Tools 配置: HarmonyOS开发者网站

• Command Line Tools for HarmonyOS
• Command Line Tools for OpenHarmony

a): 设置环境变量

# Open Harmony SDK & HDC
export HDC_SERVER_PORT=7035
export OHPM_HOME=/Users/xxx/ohos/tools/oh-command-line-tools/ohpm
export PATH=/Users/xxx/ohos/tools/oh-command-line-tools/sdkmanager/bin:$PATH
export PATH=$PATH:$OHPM_HOME/bin
export OHOS_SDK_HOME=/Users/xxx/ohos/tools/oh-command-line-tools/sdk
export HDC_HOME=/Users/xxx/ohos/tools/oh-command-line-tools/sdk/11/toolchains
#export HDC_HOME=/Users/xxx/ohos/tools/hwsdk/openharmony/9/toolchains
export PATH=$PATH:$HDC_HOME

export PATH=/Users/xxx/ohos/tools/command-line-tools/sdkmanager/bin:$PATH
export HOS_SDK_HOME=/Users/xxx/ohos/tools/hwsdk

b): 执行 **ohsdkmgr list**, API(10、11) 需去官网自行下载： 构建详情 (openharmony.cn)

c): 下载完成后放sdk这个层级下

d): 分别进入

• sdk/11/ets/build-tools/ets-loader
• sdk/11/js/build-tools/ace-loader

e): 执行 **npm install**

f): 将oh command tools 里面的 native 文件夹拷贝至 **engine/ndk/mac/4.0** 目录下，如下图

g): 编译引擎，切换到 **engine** 目录下，执行 **make** 命令（此过程预计1小时左右）

编译出来的产物

• ohos_debug_unopt_arm64

• ohos_release_arm64

2、鸿蒙签名配置

a): 下载鸿蒙签名工具：

git clone https://gitee.com/openharmony/developtools_hapsigner.git

b)：设置环境变量

# Harmony sign tool
export SIGN_TOOL_HOME=/Users/xxx/ohos/tools/developtools_hapsigner/autosign

c): 增加 **profile_tmp_template.json** 内容如下, 其中 **{{ohosId}}** 为创建的 **Flutter** 应用名称

{
    "version-name": "2.0.0",
    "version-code": 2,
    "app-distribution-type": "os_integration",
    "uuid": "5027b99e-5f9e-465d-9508-a9e0134ffe18",
    "validity": {
        "not-before": 1594865258,
        "not-after": 1689473258
    },
    "type": "release",
    "bundle-info": {
        "developer-id": "OpenHarmony",
        "distribution-certificate": "-----BEGIN CERTIFICATE-----\nMIICSTCCAc+gAwIBAgIFAJV7uNUwCgYIKoZIzj0EAwIwYzELMAkGA1UEBhMCQ04x\nFDASBgNVBAoMC09wZW5IYXJtb255MRkwFwYDVQQLDBBPcGVuSGFybW9ueSBUZWFt\nMSMwIQYDVQQDDBpPcGVuSGFybW9ueSBBcHBsaWNhdGlvbiBDQTAeFw0yMjAxMjkw\nNTU0MTRaFw0yMzAxMjkwNTU0MTRaMGgxCzAJBgNVBAYTAkNOMRQwEgYDVQQKDAtP\ncGVuSGFybW9ueTEZMBcGA1UECwwQT3Blbkhhcm1vbnkgVGVhbTEoMCYGA1UEAwwf\nT3Blbkhhcm1vbnkgQXBwbGljYXRpb24gUmVsZWFzZTBZMBMGByqGSM49AgEGCCqG\nSM49AwEHA0IABAW8pFu7tHGUuWtddD5wvazc1qN8ts9UPZH4pecbb/bSFWKh7X7R\n/eTVaRrCTSSdovI1dhoV5GjuFsKW+jT2TwSjazBpMB0GA1UdDgQWBBScyywAaAMj\nI7HcuIS42lvZx0Lj+zAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUE\nDDAKBggrBgEFBQcDAzAYBgwrBgEEAY9bAoJ4AQMECDAGAgEBCgEAMAoGCCqGSM49\nBAMCA2gAMGUCMFfNidGo6uK6KGT9zT1T5bY1NCHTH3P3muy5X1xudOgxWoOqIbnk\ntmQYB78dxWEHLQIxANfApAlXAD/0hnyNC8RDzfLOPEeay6jU9FXJj3AoR90rwZpR\noN9sYD6Oks4VGRw6yQ==\n-----END CERTIFICATE-----\n",
        "bundle-name": "{{ohosId}}",
        "apl": "normal",
        "app-feature": "hos_normal_app"
    },
    "acls": {
        "allowed-acls": [
            ""
        ]
    },
    "permissions": {
        "restricted-permissions": []
    },
    "issuer": "pki_internal"
}

d): 编辑配置文件

• autosign.config
• createAppCertAndProfile.config

修改值：sign.profile.inFile=profile_tmp.json

e): 切换 Java 版本11 (签名工具基于Gradle 7.1编译构建)

f): 切换至 **developtools_hapsigner/hapsigntool** **目录，**执行 **gradle build** 或者 **gradle jar,**确保 **hap-sign-tool.jar** 生成

六、鸿蒙 Flutter 配置

a): 下载 Flutter

git clone https://gitee.com/openharmony-sig/flutter_flutter.git

b): 设置环境变量

# Harmony flutter
export PATH=/Users/xxx/ohos/flutter/flutter_flutter/bin:$PATH
export PATH=/Users/xxx/ohos/flutter/flutter_flutter/bin/cache/dart-sdk/bin:$PATH
export PATH=/Users/xxx/ohos/flutter/flutter_flutter/.pub-cache/bin:$PATH
export FLUTTER_GIT_URL=https://gitee.com/openharmony-sig/flutter_flutter.git
export PUB_HOSTED_URL=https://pub.flutter-io.cn

c): 执行 **flutter doctor -v**

[✓] Flutter (Channel master, 3.7.12, on macOS 12.7 21G816 darwin-x64, locale zh-Hans-CN)
    • Flutter version 3.7.12 on channel master at /Users/xxx/ohos/flutter/flutter_flutter
    • Upstream repository https://gitee.com/openharmony-sig/flutter_flutter.git
    • FLUTTER_GIT_URL = https://gitee.com/openharmony-sig/flutter_flutter.git
    • Framework revision 00cc3dce34 (2 weeks ago), 2023-12-11 13:38:48 +0000
    • Engine revision 1a65d409c7
    • Dart version 2.19.6
    • DevTools version 2.20.1
    • Pub download mirror https://pub.flutter-io.cn
    • Flutter download mirror https://storage.flutter-io.cn

[✓] OpenHarmony toolchain - develop for OpenHarmony devices
    • OpenHarmony Sdk location: /Users/xxx/ohos/tools/oh-command-line-tools/sdk, available api versions has [9, 10]
    • hdc version 2.0.0
    • ohpm version 1.2.0
    • signTool location:/Users/xxx/ohos/tools/developtools_hapsigner/autosign

[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.2)
    • Android SDK at /Users/xxx/Library/Android/sdk
    • Platform android-33, build-tools 33.0.2
    • ANDROID_HOME = /Users/xxx/Library/Android/sdk
    • Java binary at: /Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 17.0.6+0-17.0.6b802.4-9586694)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 14.2)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 14C18
    • CocoaPods version 1.12.1

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2022.2)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 17.0.6+0-17.0.6b802.4-9586694)

[✓] IntelliJ IDEA Ultimate Edition (version 2020.1)
    • IntelliJ at /Applications/IntelliJ IDEA.app
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart

[✓] VS Code (version 1.84.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.78.0

[✓] Connected device (2 available)
    • macOS (desktop) • macos  • darwin-x64     • macOS 12.7 21G816 darwin-x64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 120.0.6099.129

[✓] HTTP Host Availability
    • All required HTTP hosts are available

d): 创建项目 **flutter create --platforms ohos flutter_harmony_demo**

Creating project flutter_harmony_demo...
Running "flutter pub get" in flutter_harmony_demo...
Resolving dependencies in flutter_harmony_demo... (1.1s)
+ async 2.10.0 (2.11.0 available)
+ boolean_selector 2.1.1
+ characters 1.2.1 (1.3.0 available)
+ clock 1.1.1
+ collection 1.17.0 (1.18.0 available)
+ cupertino_icons 1.0.6
+ fake_async 1.3.1
+ flutter 0.0.0 from sdk flutter
+ flutter_lints 2.0.3 (3.0.1 available)
+ flutter_test 0.0.0 from sdk flutter
+ js 0.6.5 (0.6.7 available)
+ lints 2.0.1 (3.0.0 available)
+ matcher 0.12.13 (0.12.16+1 available)
+ material_color_utilities 0.2.0 (0.8.0 available)
+ meta 1.8.0 (1.11.0 available)
+ path 1.8.2 (1.9.0 available)
+ sky_engine 0.0.99 from sdk flutter
+ source_span 1.9.1 (1.10.0 available)
+ stack_trace 1.11.0 (1.11.1 available)
+ stream_channel 2.1.1 (2.1.2 available)
+ string_scanner 1.2.0
+ term_glyph 1.2.1
+ test_api 0.4.16 (0.7.0 available)
+ vector_math 2.1.4
Changed 24 dependencies in flutter_harmony_demo!
OhosDependenciesManager: it no need to add plugins dependencies.
Wrote 62 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd flutter_harmony_demo
  $ flutter run

Your application code is in flutter_harmony_demo/lib/main.dart.

e): 修改工程目录下 **flutter_harmony_demo/ohos/build-profile.json5** 文件

"app": {
    "signingConfigs": [],
    # 移到这个层级
    "compileSdkVersion": 9,
    "compatibleSdkVersion": 9,
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        # 去掉
        # "compileSdkVersion": 9,
        # "compatibleSdkVersion": 9,
        # 改成 OpenHarmony
        "runtimeOS": "OpenHarmony",
      }
    ]
  },

f): 开始编译

flutter build hap --local-engine-src-path /Users/xxx/ohos/flutter/engine/src --local-engine ohos_release_arm64

start hap build...
ohosPluginsManager: no need to install ohos plugins
check platform environment
current platform environment PUB_HOSTED_URL = https://pub.flutter-io.cn
current platform environment FLUTTER_STORAGE_BASE_URL = https://storage.flutter-io.cn
current platform environment OHPM_HOME = /Users/xxx/ohos/tools/oh-command-line-tools/ohpm
Compiling ohos_aot_bundle_release_ohos-arm64 for the Ohos...      1,475ms
copy flutter assets to project start
copy directory from /Users/xxx/Desktop/oh-app/flutter_harmony_demo/build/ohos/flutter_assets to
/Users/xxx/Desktop/oh-app/flutter_harmony_demo/ohos/entry/src/main/resources/rawfile/flutter_assets
copy flutter assets to project end
copy flutter runtime to project start
flutterEngineSoPath: /Users/xxx/ohos/flutter/engine/src/out/ohos_release_arm64/libflutter.so
copy flutter runtime to project end
install completed in 0s 205ms
ohpm install success.
> hvigor Finished :entry:clean... after 2 ms
> hvigor WARN: Currently, the device type 'phone' is not supported in module.json5 or config.json. You are advised to change the device
type to 'default'.


> hvigor Finished :entry:default@PreBuild... after 210 ms
> hvigor Finished :entry:default@GenerateMetadata... after 14 ms
> hvigor Finished ::clean... after 1 ms
> hvigor Finished :entry:default@MergeProfile... after 4 ms
> hvigor Finished :entry:default@GenerateLoaderJson... after 4 ms
> hvigor Finished :entry:default@BuildNativeWithCmake... after 1 ms
> hvigor Finished :entry:default@MakePackInfo... after 11 ms
> hvigor Finished :entry:default@ProcessProfile... after 122 ms
> hvigor Finished :entry:default@BuildNativeWithNinja... after 1 ms
> hvigor Finished :entry:default@ProcessResource... after 2 ms
> hvigor Finished :entry:default@ProcessLibs... after 91 ms
> hvigor Finished :entry:default@CompileResource... after 269 ms
> hvigor Finished :entry:default@BuildJS... after 8 ms
> hvigor WARN: ArkTS:WARN File:
/Users/xxx/Desktop/oh-app/flutter_harmony_demo/ohos/entry/oh_modules/.ohpm/@ohos+flutter_ohos@file+..+har+flutter_embedding.har
/oh_modules/@ohos/flutter_ohos/src/main/ets/embedding/engine/FlutterNapi.ts:16:21
 Currently module for 'libflutter.so' is not verified. If you're importing napi, its verification will be enabled in later SDK version.
 Please make sure the corresponding .d.ts file is provided and the napis are correctly declared.


> hvigor Finished :entry:default@CompileArkTS... after 6 s 256 ms
> hvigor Finished :entry:default@PackageHap... after 3 s 169 ms
> hvigor WARN: Will skip sign 'hap'. No signingConfigs profile is configured in current project.
               If needed, configure the signingConfigs in
               /Users/xxx/Desktop/oh-app/flutter_harmony_demo/ohos/build-profile.json5 .


> hvigor Finished :entry:default@SignHap... after 3 ms
> hvigor Finished :entry:assembleHap... after 1 ms
> hvigor BUILD SUCCESSFUL in 12 s 87 ms
success! when invoke: /Users/xxx/Desktop/oh-app/flutter_harmony_demo/ohos/hvigorw clean assembleHap --no-daemon.
ohosId bundleName: com.example.flutter_harmony_demo
Success!
Success!
python3 /Users/xxx/ohos/tools/developtools_hapsigner/autosign/autosign.py createAppCertAndProfile invoke success.
Success!
python3 /Users/xxx/ohos/tools/developtools_hapsigner/autosign/autosign.py signHap invoke success.

g): 构建的鸿蒙包目录 flutter_harmony_demo**/ohos/entry/build/default/outputs/default**

.
├── entry-default-signed.hap
├── entry-default-unsigned.hap
└── pack.info

能完成到这一步，最终将安装运行成功。