使用Flutter从0到1构建OpenHarmony/HarmonyOS应用

- [1. 环境准备](#1. 环境准备)
- - [1.1 下载并安装OpenHarmony最新DevEco Studio开发工具，及其依赖环境](#1.1 下载并安装OpenHarmony最新DevEco Studio开发工具，及其依赖环境)
  - - [1.1.1 官方下载地址](#1.1.1 官方下载地址)
    - [1.1.2 下载清单](#1.1.2 下载清单)
    - [1.1.3 OpenHarmony开发环境的前置环境依赖](#1.1.3 OpenHarmony开发环境的前置环境依赖)
- [2. 安装说明](#2. 安装说明)
- - [2.3 环境变量配置](#2.3 环境变量配置)
  - - [2.3.1 Mac、Linux：](#2.3.1 Mac、Linux：)
    - - 编辑配置文件
        
        在文件中配置环境变量：
        
        保存并退出
        
        应用配置
    - [2.3.2 Windows：](#2.3.2 Windows：)
    - - 打开系统环境变量设置
        
        配置环境变量
  - [2.4 运行模拟器或真机](#2.4 运行模拟器或真机)
- 3.集成与调试OpenHarmony版Flutter
- - [3.1 检查环境](#3.1 检查环境)
  - [3.2 创建Flutter工程](#3.2 创建Flutter工程)
  - [3.3 HarmonyOS/OpenHarmony真机运行Flutter项目](#3.3 HarmonyOS/OpenHarmony真机运行Flutter项目)
  - - [3.3.1 项目签名](#3.3.1 项目签名)
    - [3.3.2 真机运行Flutter项目](#3.3.2 真机运行Flutter项目)
  - [3.4 安装成功](#3.4 安装成功)
  - [3.5 模拟器运行常见问题](#3.5 模拟器运行常见问题)
  - - [3.5.1 无法创建模拟器](#3.5.1 无法创建模拟器)
    - [3.5.2 Windows或Mac x86架构无法运行模拟器](#3.5.2 Windows或Mac x86架构无法运行模拟器)
  - [3.6 pub upgrade常见问题](#3.6 pub upgrade常见问题)
  - - [3.6.1 pub upgrade耗时较长](#3.6.1 pub upgrade耗时较长)
  - [3.7 签名配置问题](#3.7 签名配置问题)

1. 环境准备

1.1 下载并安装OpenHarmony最新DevEco Studio开发工具，及其依赖环境

1.1.1 官方下载地址

OpenHarmony开发套件官方下载地址

注意事项：

目前支持操作系统Linux、Mac、Windows环境下使用。
mac系统在终端输入 uname -m 判断系统架构选择对应的开发组件套
如果输出结果是 x86_64，则表示你的系统是x86-64架构
如果输出结果是 arm64，则表示你的系统是arm64架构。

1.1.2 下载清单

根据自身所用电脑系统下载对应最新版 DevEco Studio。
若无OpenHarmony真机，需在DevEco Studio中下载模拟器。

模拟器下载和安装步骤见：[安装模拟器](#### 2.2 安装模拟器)
下载OpenHarmony版 flutter。

通过代码工具下载仓库代码并指定dev或master分支，dev不断在更新相比master拥有更多功能。
复制代码
```
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
git checkout -b dev origin/dev
或者
git checkout -b oh-3.27.0-release
```

1.1.3 OpenHarmony开发环境的前置环境依赖

由于OpenHarmony系统sdk存在java环境依赖，在oracle官网或openjdk官网下载jdk 17环境，并进行相应配置。
执行如下命令，检查JDK安装结果，安装成功后进行后续操作。
sh 复制代码
```
java -version
```

2. 安装说明

2.3 环境变量配置

2.3.1 Mac、Linux：

编辑配置文件

打开终端，执行以下命令编辑配置文件:

bash 复制代码

vim ~/.zshrc

在文件中配置环境变量：

bash 复制代码

# 配置JDK 17
export JAVA_HOME=<JAVA_HOME path>/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# 配置OpenHarmony SDK, ohpm, hvigor, node
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # mac环境
export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin
export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin

#配置Flutter
export PUB_CACHE=~/PUB
export PATH=<flutter_flutter path>/bin:$PATH
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

保存并退出

按Esc键进入命令模式，输入 :wq后按 Enter 键保存并推出编辑器。
*

应用配置

执行以下命令重新加载配置使其立即生效：

bash 复制代码

source ~/.zshrc

2.3.2 Windows：

打开系统环境变量设置

通过以下路径访问环境变量配置界面：

此电脑 （右键）→ 属性 → 高级系统设置 → 高级选项卡 → 环境变量
*

配置环境变量

在环境变量面板，添加以下配置：

① 配置配置 JDK 17

变量	值	作用域
`JAVA_HOME`	`<JDK path >`	系统变量
`Path`	`%JAVA_HOME%\bin`	追加到现有值

② 配置 OpenHarmony SDK ,ohpm, hvigor, node

变量	值	作用域
`TOOL_HOME`	`<Deveco-studio Path>`	系统变量
`DEVECO_SDK_HOME`	`%TOOL_HOME%\sdk`	系统变量
`Path`	`%TOOL_HOME%\tools\ohpm\bin`	系统变量
`Path`	`%TOOL_HOME%\tools\hvigor\bin`	系统变量
`Path`	`%TOOL_HOME%\tools\node\bin`	系统变量

③ 配置 Flutter

变量	值	作用域
`PATH`	`<flutter_flutter Path>\bin`	系统变量
`PUB_CACHE`	`<PUB Path>`	系统变量
`PUB_HOSTED_URL`	`https://pub.flutter-io.cn`	系统变量
`FLUTTER_STORAGE_BASE_URL`	`https://storage.flutter-io.cn`	系统变量

2.4 运行模拟器或真机

3.集成与调试OpenHarmony版Flutter

3.1 检查环境

运行flutter doctor -v检查环境变量配置是否正确，Futter与Harmony应都为ok标识，若两处提示缺少环境，按提示补上相应环境即可。

此图里面就缺少两处环境变量配置，需要手动配置；

3.2 创建Flutter工程

创建工程与编译命令，

sh 复制代码

# 创建工程 方式一 该方式只创建了ohos平台
flutter create --platforms ohos <projectName> 

# 创建工程 方式二 该方式创建了android,ios,ohos三个平台
flutter create  <projectName> 

# 进入工程根目录编译hap包
flutter build hap --debug

编译产物在 ${projectName}/ohos/entry/build/default/outputs/default/entry-default-signed.hap 下。

3.3 HarmonyOS/OpenHarmony真机运行Flutter项目

3.3.1 项目签名

在运行到真机之前，需要对项目进行签名，具体操作如下：

在DevEco Studio中：

File → Project Structure → Project → Signing Configs
勾选"Automatically generate signature"
点击"OK"

3.3.2 真机运行Flutter项目

通过flutter devices指令发现真机设备之后，获取device-id。

方式一：进入项目目录指定构建方式编译hap包并安装到OpenHarmony手机中。

sh 复制代码

 flutter run --debug -d <deviceId>

方式二：进入工程根目录编译hap包,然后安装到OpenHarmony手机中。

sh 复制代码

 flutter build hap --debug
 hdc -t <deviceId> install <hap file path>

方式三：使用DevEcoStudio 选择设备为真机，点击启动。

3.4 安装成功

成功运行后，您应该能看到：

鸿蒙应用正常启动
Flutter页面在应用中正确渲染
Flutter组件响应正常

3.5 模拟器运行常见问题

3.5.1 无法创建模拟器

情况1：使用实名制认证的账号进行签名

3.5.2 Windows或Mac x86架构无法运行模拟器

由于模拟器当前仅支持Mac arm架构，且flutter应用尚未适配x86架构，因此在Windows或Mac的x86运行模拟器会遇到限制。

3.6 pub upgrade常见问题

3.6.1 pub upgrade耗时较长

情况1：首次加载因为需要拉取的文件较多，根据自身网络情况所需花费的时间有较大差异，请耐心等待,如果下载失败，建议检查网络连接或更换代理后再次尝试。

情况2：删除 flutter_flutter/bin/cache 文件后重试。

情况3：更换镜像源，如：

复制代码

PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter

3.7 签名配置问题

症状：安装应用时提示签名错误

解决方案：

在DevEco Studio中重新配置自动签名

清理项目：Build → Clean Project

重新构建：Build → Rebuild Project