欢迎加入 CPF-Flutter 社区，一起交流 Flutter 在 OpenHarmony/HarmonyOS 上的开发经验。

我这次的目标很直接：在 Mac 上新建一个 Flutter OH 工程，把它装到 HarmonyOS 手机上，再试一下按钮点击和热重载。听起来不复杂，实际操作时还是碰到了几个小坑，比如工程放在中文路径下无法构建、下载地址配错后报 404，以及没有签名只能得到 unsigned HAP。

最后应用跑在华为畅享 90 Pro Max 上，系统版本是 HarmonyOS 7.0.0.105，API 26。下图不是模拟器，右下角的加号点了 4 次，页面上的计数也正常变成了 4。

图 1：Flutter 默认计数器应用运行在 HarmonyOS 7 真机上。

这篇文章不展开讲 Flutter 的基础概念，只记录我实际用到的版本、命令和处理办法。大致过程如下。

图 2：从环境准备到应用在手机上运行，整个流程共经历这几个关键环节。

一、我用的版本

先把环境列出来，方便大家对照。同一条命令在不同版本上表现可能不一样，遇到问题时，版本信息比一句“我这里不行”有用得多。

项目	本次使用的版本
电脑	Apple Silicon Mac，arm64
DevEco Studio	26.0.0 Release
HarmonyOS SDK	HarmonyOS 7.0.0，API 26
Flutter OH	3.41.10-ohos-1.0.1
Dart	3.11.5
ohpm	26.0.0.630
hdc	3.2.0f
测试手机	华为畅享 90 Pro Max，HarmonyOS 7.0.0.105

为什么没有用数字更大的 3.44.9

Flutter OH 和 Flutter 官网下载的版本不是一回事。普通 Flutter SDK 不能直接拿来构建 OHOS 工程，需要使用 CPF-Flutter 维护的适配版本。

我在 2026 年 9 月 6 日查看 AtomGit 仓库标签时，3.41.10-ohos-1.0.1 是最新的正式稳定标签。仓库里确实还有 3.44.9+ohos-0.0.1-canary1，但它后面带着 canary1，目前还是预览版。为了少踩一些版本变化带来的坑，我这次选了 3.41.10 稳定版。以后再照着本文操作时，最好先看一眼仓库的新标签，如果 3.44.9 已经出了正式版，就应该重新测试后再升级。

git clone --branch 3.41.10-ohos-1.0.1 --depth 1 \
  https://atomgit.com/CPF-Flutter/flutter_flutter.git \
  "$HOME/Developer/flutter-oh"

cd "$HOME/Developer/flutter-oh"
git describe --tags --exact-match HEAD
flutter --version

图 3：根据终端实测结果整理的 Flutter OH、Dart、JDK、ohpm 和 hdc 版本。

二、准备 DevEco Studio 和 SDK

DevEco Studio 安装好以后，先打开 SDK Manager，看看 API 26 有没有下载。它自己带了 JBR、ohpm、Hvigor、Node.js 和 hdc，我没有再单独装一套同类工具，省得系统里同时出现几个 Java 或 Node，出错后还要猜到底调用了哪一个。

我机器上的安装目录是：

/Applications/DevEco-Studio.app/Contents

如果你改过安装位置，下面的环境变量也要跟着改。可以先去目录里确认这几个位置是否存在：

jbr/Contents/Home
tools/ohpm/bin
tools/hvigor/bin
sdk/default/openharmony/toolchains

三、环境变量怎么配

我的 Mac 使用 zsh，所以把配置写进了 ~/.zshrc。Flutter SDK 和准备编译的工程都放在纯英文路径下，不要急着问为什么，后面会说到我在中文路径上遇到的问题。

export FLUTTER_OH_HOME="$HOME/Developer/flutter-oh"
export DEVECO_HOME="/Applications/DevEco-Studio.app/Contents"
export DEVECO_SDK_HOME="$DEVECO_HOME/sdk"
export HOS_SDK_HOME="$DEVECO_SDK_HOME"
export JAVA_HOME="$DEVECO_HOME/jbr/Contents/Home"

export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
export FLUTTER_OHOS_STORAGE_BASE_URL="https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com"
export FLUTTER_GIT_URL="https://atomgit.com/CPF-Flutter/flutter_flutter.git"

export PATH="$FLUTTER_OH_HOME/bin:$DEVECO_HOME/tools/ohpm/bin:$DEVECO_HOME/tools/hvigor/bin:$DEVECO_HOME/sdk/default/openharmony/toolchains:$JAVA_HOME/bin:$PATH"

写完以后，新开一个终端，或者手动执行一次：

source ~/.zshrc

然后把常用工具都检查一遍：

flutter --version
java -version
ohpm --version
hdc version
flutter doctor -v

这里不用强求每一项都是绿色。我只做 OHOS 工程，所以重点看 HarmonyOS toolchain。它能找到 OpenHarmony SDK、ohpm、Node 和 Hvigorw，这部分就可以继续往下走。

图 4：根据 flutter doctor -v 实测输出整理，HarmonyOS 工具链已经可用。

我的检查结果里，Android SDK 和 Xcode 仍然有警告。这不会挡住 OHOS 工程。如果还要打 Android 或 iOS 包，再回来补它们就行，没必要现在为了清掉两个红色提示折腾半天。

四、创建 OHOS 工程

我专门建了一个英文工作目录：

mkdir -p "$HOME/Developer/flutter-oh-workspace"
cd "$HOME/Developer/flutter-oh-workspace"

flutter create --platforms ohos --org com.example flutter_oh_demo
cd flutter_oh_demo
flutter pub get

图 5：工程创建完成，Flutter 写入了 45 个文件。

这里用了 --platforms ohos，因为这次只测 HarmonyOS。生成后的目录里既有大家熟悉的 lib、test 和 pubspec.yaml，也有一个 ohos 目录。页面代码还是写在 lib 里，签名、Ability、资源和 HarmonyOS 构建配置则放在 ohos 里。

工程不要放在中文路径下

一开始我把工程建在活动资料目录里，那个目录名包含中文。执行构建时，Hvigor 在 Dart 编译之前就停了。后来把 Flutter SDK 和工程移到 ~/Developer/flutter-oh-workspace，同样的代码就能正常构建。

所以我的做法是：文章和截图继续放中文资料目录，实际参与编译的工程放英文目录。两边用软链接关联也可以。遇到类似报错时先换路径，别急着改业务代码。

五、签名 HAP 是第一个容易卡住的地方

第一次运行 flutter build hap --debug，我只拿到了 entry-default-unsigned.hap。这个文件虽然说明代码已经编译了，但不能直接作为真机安装结果。

用 DevEco Studio 打开工程里的 ohos 目录，然后进入：

File → Project Structure → Project → Signing Configs

选中默认产品并开启自动签名。DevEco Studio 会生成调试证书、Profile 和密钥库配置。签名完成后，我回到 Flutter 工程根目录执行了三条命令：

flutter analyze
flutter test
flutter build hap --debug

图 6：构建成功后，输出文件名里已经出现 signed。

图 7：静态检查没有报错，测试通过，签名调试包也顺利生成。

这次生成的签名 HAP 大约 92 MB，位置是：

build/ohos/hap/entry-default-signed.hap

还有一个安全问题要提醒一下。自动签名后，ohos/build-profile.json5 里会出现证书路径和签名材料。发文章、提 Issue 或上传公开仓库之前，别把这个文件的敏感内容原样贴出去。截图也要检查，不要只盯着控制台有没有报错。

六、连上手机跑一次

手机要先打开开发者模式和 USB 调试，插线以后还要在手机上确认授权。我先用下面两条命令看设备：

hdc list targets
flutter devices

图 8：Flutter 已经识别出 API 26 的 ohos-arm64 手机，设备序列号做了隐藏处理。

看到设备以后，在项目根目录执行：

flutter run -d <device-id> --debug

图 9：这条命令会构建 HAP、安装应用，然后连接 Dart VM Service。

终端里会先看到 Hvigor 构建，接着是安装 HAP 和启动 EntryAbility。出现 Flutter run key commands，说明 Flutter 已经连上手机上的调试进程。这时候输入小写 r 就能热重载。

Performing hot reload...
Reloaded 0 libraries in 237ms
(compile: 5 ms, reload: 0 ms, reassemble: 112 ms).

图 10：在运行会话中输入 r，这次热重载用了 237 毫秒。

到这里我才把环境算作可用。因为页面已经装到了手机上，右下角按钮能点，计数会变化，终端也能热重载。只看到 flutter doctor 通过，还不能说明签名、安装和调试都没问题。

七、我遇到的几个问题

1. 新终端找不到 flutter 或 ohpm

先执行 source ~/.zshrc。如果还是找不到，再运行：

command -v flutter
command -v ohpm

这两条命令会直接告诉你当前调用的是哪个文件。有时工具已经装好了，只是这个终端没有读到新配置。脚本运行在非交互 Shell 里时，也可能不会自动加载 ~/.zshrc。

2. 下载 OHOS 构建文件时出现 404

我踩过这个坑。标准 Flutter 文件和 OHOS 适配文件不在同一个下载地址，下面两个变量不能写成同一个值：

FLUTTER_STORAGE_BASE_URL
FLUTTER_OHOS_STORAGE_BASE_URL

如果混在一起，下载 engine_stamp.json 一类文件时就可能返回 404。按前面的配置把两个地址分开，再重新执行构建即可。

3. Hvigor 提示工程路径不合法

先看路径里有没有中文、空格或特殊字符。我的问题就是中文目录造成的。把项目挪到纯英文路径后恢复正常，这时没有必要去改 main.dart。

4. 只有 unsigned HAP

这说明项目已经编译，但签名还没配好。去 DevEco Studio 开启自动签名，再跑一次 flutter build hap --debug。看到 entry-default-signed.hap 后，再连接手机运行。

如果 flutter devices 里没有手机，就按这个顺序检查：数据线、手机上的授权提示、hdc list targets、flutter devices。一步一步看，比直接重装 DevEco Studio 快得多。

八、怎么确认已经跑通

我最后按下面几项检查：

1. flutter doctor -v 能识别 HarmonyOS 工具链；
2. flutter devices 能看到 ohos-arm64 手机；
3. flutter analyze 和 flutter test 没有报错；
4. 构建目录里有 entry-default-signed.hap；
5. flutter run 能安装应用，输入 r 能热重载。

这五项都没问题以后，就可以在这套环境上继续做 Flutter 应用迁移、平台通道或者三方插件适配了。对我来说，最花时间的不是写那个计数器页面，而是把路径、镜像地址和签名配置理顺。好在这些问题处理一次以后，后面新建工程就省事多了。

欢迎加入 CPF-Flutter 社区，查看 Flutter OH 源码、示例和适配进展。