Flutter OpenHarmony 环境搭建

欢迎大家加入开源鸿蒙跨平台开发者社区

本文档将指导你完成 OpenHarmony 版 Flutter 开发环境的完整搭建过程。

[1. 安装 Git 与 DevEco](#1. 安装 Git 与 DevEco)
[2. 配置 AtomGit](#2. 配置 AtomGit)
[3. 下载 OpenHarmony 版 Flutter](#3. 下载 OpenHarmony 版 Flutter)
[4. 安装 Oracle JDK 17](#4. 安装 Oracle JDK 17)
[5. 配置环境变量](#5. 配置环境变量)
[6. 验证环境配置](#6. 验证环境配置)

1. 安装 Git 与 DevEco

1.1 下载并安装 DevEco Studio

DevEco Studio 是华为提供的 OpenHarmony /HarmonyOS应用开发 IDE。

下载地址： https://developer.huawei.com/consumer/cn/download/

选择 macOS 版本下载并安装。

1.2 安装 Git

下载地址： https://git-scm.com/

选择 macOS 版本下载并安装。

提示： 也可以通过 Homebrew 安装：
bash 复制代码
brew install git

2. 配置 AtomGit

2.1 生成 SSH 密钥

了解如何生成 SSH Key。

在终端中执行以下命令生成 SSH 密钥：

bash 复制代码

ssh-keygen -t ed25519 -C "your_email@example.com"

注意： 请将 your_email@example.com 替换为你的邮箱地址。

执行过程中会提示输入保存路径和密码，可以直接按回车使用默认设置。

2.2 复制公钥

公钥默认保存在 ~/.ssh/id_ed25519.pub 文件中，使用以下命令查看并复制：

bash 复制代码

cat ~/.ssh/id_ed25519.pub

或者使用 macOS 的 pbcopy 命令直接复制到剪贴板：

bash 复制代码

pbcopy < ~/.ssh/id_ed25519.pub

2.3 在 GitCode 添加 SSH 公钥

登录 GitCode
进入「个人设置」→「安全设置」→「SSH 公钥」
点击「+ SSH 公钥」按钮
在"公钥名称"一栏中，为公钥添加一个描述性名称（如：MacBook Pro）
将复制的公钥内容粘贴到"公钥"文本框中
点击「新建」完成操作

重要提示：

确保复制了整个密钥，以 ssh-ed25519（或 ssh-rsa）开头，并以邮箱地址结尾

不要包含多余的空格或换行符

2.4 测试 SSH 连接

在终端中运行以下命令测试 SSH 连接：

bash 复制代码

ssh -T git@atomgit.com

首次连接时，会显示以下信息：

text 复制代码

The authenticity of host 'gitcode.com (121.36.6.22)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitcode.com' (ECDSA) to the list of known hosts.

输入 yes 并按回车，将 AtomGit 添加到已知主机列表中。

成功后，会显示欢迎信息：

text 复制代码

Welcome to AtomGit, [your_username]

2.5 排除连接问题

如果未出现欢迎消息，可以使用详细模式进行调试：

bash 复制代码

ssh -Tv git@atomgit.com

这将显示详细的连接过程，帮助你定位问题。

3. 下载 OpenHarmony 版 Flutter

3.1 克隆仓库

使用 Git 克隆 OpenHarmony 版 Flutter 仓库：

bash 复制代码

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git

3.2 切换到指定分支

进入项目目录并切换到开发分支：

bash 复制代码

cd flutter_flutter
git checkout -b oh-3.35.7-dev origin/oh-3.35.7-dev

说明：

dev 分支持续更新，包含最新功能和修复

master 分支相对稳定，但功能可能较旧

建议开发时使用 dev 分支以获取最新特性

项目地址： https://atomgit.com/openharmony-tpc/flutter_flutter

4. 安装 Oracle JDK 17

OpenHarmony Flutter 开发需要 JDK 17 环境。

4.1 下载 JDK 17

访问 Oracle JDK 17 官方下载页面：

下载地址： https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html

选择 macOS 版本的 JDK 17（.dmg 文件）进行下载。

4.2 安装 JDK

找到下载的 .dmg 文件
双击打开安装包
按照安装向导的提示完成安装
安装完成后，可以关闭安装窗口

4.3 验证安装

在终端中执行以下命令验证安装是否成功：

bash 复制代码

java -version

应该显示类似以下信息：

text 复制代码

java version "17.0.x" 2024-xx-xx LTS
Java(TM) SE Runtime Environment (build 17.0.x+xx-LTS-xxx)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.x+xx-LTS-xxx, mixed mode, sharing)

同时验证 Java 编译器：

bash 复制代码

javac -version

应该显示：

text 复制代码

javac 17.0.x

5. 配置环境变量

5.1 编辑配置文件

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

bash 复制代码

vim ~/.zshrc

如果文件不存在，该命令会自动创建。

5.2 添加环境变量

在文件中添加以下配置：

bash 复制代码

# 配置 JDK 17
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

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

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

注意：

请将 /path/to/flutter_flutter/bin 替换为你实际的 Flutter 安装路径

例如：/Users/yourname/flutter/flutter_flutter/bin

5.3 保存并退出

按 Esc 键进入命令模式
输入 :wq 并按 Enter 键保存并退出编辑器

5.4 应用配置

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

bash 复制代码

source ~/.zshrc

6. 验证环境配置

6.1 运行 Flutter Doctor

在终端中执行以下命令检查环境配置：

bash 复制代码

flutter doctor -v

复制代码

flutter  --version
Flutter 3.35.8-ohos-0.0.3 • channel [user-branch] •
https://gitcode.com/openharmony-tpc/flutter_flutter.git
Framework • revision cfae25104a (13 hours ago) • 2026-03-26 20:58:40 +0800
Engine • hash 6b24e1b529bc46df7ff397667502719a2a8b6b72 (revision 035316565a) (5
months ago) • 2025-10-21 14:28:01.000Z
Tools • Dart 3.9.2 • DevTools 2.48.0

6.2 检查结果

检查输出结果，确保以下项目都显示为 ✓（OK）：

Flutter - Flutter SDK 版本和路径
OpenHarmony - OpenHarmony SDK 和工具链

6.3 解决问题

如果出现警告或错误，按照提示进行修复：

缺少 JDK：检查 JAVA_HOME 配置
缺少 DevEco SDK：检查 TOOL_HOME 和 DEVECO_SDK_HOME 配置
缺少 ohpm/hvigor：检查 PATH 配置
网络问题：检查 Flutter 镜像源配置

参考资源

常见问题

Q1: SSH 连接失败怎么办？

A: 检查以下几点：

确认公钥已正确添加到 GitCode
使用 ssh -Tv git@atomgit.com 查看详细错误信息
检查网络连接是否正常

Q2: Flutter doctor 提示缺少 OpenHarmony 环境？

A: 确认以下配置：

DevEco Studio 是否正确安装
TOOL_HOME 路径是否正确
是否已执行 source ~/.zshrc 应用配置

Q3: 如何切换 Flutter 分支？

A: 使用以下命令：

bash 复制代码

cd flutter_flutter
git checkout -b oh-3.35.7-dev origin/oh-3.35.7-dev

Q4: JDK 版本不兼容怎么办？

A: 确保：

安装的是 JDK 17（不是 JDK 8 或 11）
JAVA_HOME 指向正确的 JDK 17 路径
已执行 source ~/.zshrc 重新加载配置

祝你开发愉快！ 🚀