Flutter 应用运行到鸿蒙 PC 指南

欢迎大家加入鸿蒙 PC 社区^[1]

Flutter 作为"一次开发,多平台部署"的跨平台框架,支持将应用部署到多种平台,包括移动设备、桌面和 Web。本文将详细介绍如何将 Flutter 应用运行在鸿蒙 PC 设备上。

前置准备

在开始之前,请确保你已经根据官方文档^[2]完成了开发环境的搭建。

一、检查开发环境

环境搭建完成后,使用以下命令检查 Flutter 环境配置:

flutter doctor -v

关键检查点:

• ✅ 确保 HarmonyOS toolchain 显示为绿色(已安装)
• ✅ 确保 Connected device 中能看到鸿蒙设备
• ❌ Android、iOS 等工具链可以忽略(仅用于鸿蒙开发)

示例输出:

[✓] HarmonyOS toolchain - develop for HarmonyOS devices    • OpenHarmony Sdk at /Applications/DevEco-Studio.app/Contents/sdk    • Ohpm version 6.1.1.816    • Node version v18.20.1    • Hvigorw binary at /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw[✓] Connected device (3 available)    • 127.0.0.1:5555 (mobile) • 127.0.0.1:5555 • ohos-arm64    • Ohos OpenHarmony-6.1.0.105 (API 23)

注意: 只要 HarmonyOS toolchain 准备就绪,就可以继续创建项目。

二、创建 Flutter 项目

2.1 创建新项目

flutter create my_appcd my_app

2.2 查看项目结构

创建完成后,项目将包含以下目录结构:

my_app/├── android/          # Android平台代码├── ios/              # iOS平台代码├── linux/            # Linux桌面平台代码├── macos/            # macOS桌面平台代码├── windows/          # Windows桌面平台代码├── web/              # Web平台代码├── ohos/             # 鸿蒙平台代码 ⭐│   ├── entry/        # 应用入口│   ├── AppScope/     # 应用范围配置│   ├── hvigor/       # 构建工具│   └── oh_modules/   # 依赖模块├── lib/              # Dart源代码│   └── main.dart     # 应用入口文件└── pubspec.yaml      # 项目配置文件

特别关注 ohos/ 目录,这是鸿蒙平台特有的配置和代码。

三、配置鸿蒙 PC 支持

默认创建的 Flutter 项目仅支持运行到鸿蒙手机设备。要支持鸿蒙 PC,需要手动添加 PC 设备类型。

3.1 修改设备类型配置

编辑文件: my_app/ohos/entry/src/main/module.json5

找到 deviceTypes 配置项,添加 "2in1" 设备类型:

"deviceTypes": [    "phone",    "2in1"  // 添加这一行以支持鸿蒙PC设备],

说明:

• phone: 手机设备
• 2in1: 平板/PC 设备(支持触控和鼠标输入)

3.2 项目签名配置

在运行到真机之前,必须对项目进行签名。

步骤 1: 打开 DevEco Studio

在 DevEco Studio 中打开项目。

步骤 2: 配置签名

1. 点击菜单 File → Project Structure
2. 选择 Signing Configs
3. 勾选 Automatically generate signature (自动生成签名)
4. 点击 Apply 和 OK

步骤 3: 验证签名

确保签名配置成功,没有报错信息。

四、连接鸿蒙 PC 设备

4.1 查看已连接的设备

使用以下命令查看已连接的鸿蒙设备:

flutter devices

示例输出:

Found 3 connected devices:  127.0.0.1:5555 (mobile) • 127.0.0.1:5555 • ohos-arm64  • Ohos OpenHarmony-6.1.0.105 (API 23)  macOS (desktop)         • macos          • darwin-arm64  Chrome (web)            • chrome         • web-javascript

4.2 获取设备 ID

记下鸿蒙设备的 ID,例如: 127.0.0.1:5555

五、运行应用到鸿蒙 PC

有三种方式可以将 Flutter 应用运行到鸿蒙 PC 设备:

方式一: 直接运行(推荐)

使用 Flutter CLI 直接运行到指定设备:

# 运行调试版本flutter run --debug -d 127.0.0.1:5555# 运行发布版本flutter run --release -d 127.0.0.1:5555

优点:

• 一键完成编译、安装和运行
• 支持热重载(Hot Reload)
• 适合开发调试

方式二: 编译 HAP 包后安装

分两步操作:先编译 HAP 包,再手动安装。

步骤 1: 编译 HAP 包

# 编译调试版本flutter build hap --debug# 编译发布版本flutter build hap --release

编译成功后,HAP 包位于: build/ohos/outputs/hap/default/

步骤 2: 使用 HDC 工具安装

# 安装HAP包到指定设备hdc -t 127.0.0.1:5555 install build/ohos/outputs/hap/default/*.hap# 启动应用hdc shell aa start -a EntryAbility -b com.example.my_app

优点:

• 可以保存 HAP 包用于分发
• 适合 CI/CD 自动化流程

方式三: 使用 DevEco Studio 运行

在 DevEco Studio 中直接运行:

1. 打开 DevEco Studio
2. 在顶部工具栏选择目标设备(鸿蒙 PC)
3. 点击运行按钮(绿色三角形)

优点:

• 图形界面操作简单
• 集成调试功能
• 适合不熟悉命令行的开发者

六、常见问题

Q1: 提示"Unable to locate device"

解决方案:

1. 确认鸿蒙 PC 已通过 USB 连接到开发机
2. 在鸿蒙 PC 上开启 USB 调试模式
3. 检查 HDC 工具是否正常工作: hdc list targets

Q2: 签名失败

解决方案:

1. 确保 DevEco Studio 已正确配置
2. 检查签名证书是否过期
3. 尝试重新生成签名配置

Q3: 应用无法在 PC 上正常运行

解决方案:

1. 确认 module.json5 中已添加 "2in1" 设备类型
2. 检查应用的 UI 布局是否适配 PC 屏幕
3. 查看设备日志: hdc shell hilog

Q4: 编译速度慢

解决方案:

1. 使用 flutter build hap --debug 而非 --release 进行快速迭代
2. 增加构建内存: 在 gradle.properties 中设置 org.gradle.jvmargs=-Xmx4g
3. 使用本地构建缓存

七、总结

通过以上步骤,你已经成功将 Flutter 应用运行到鸿蒙 PC 设备上了!

关键步骤回顾:

1. ✅ 检查 Flutter 环境配置
2. ✅ 创建 Flutter 项目
3. ✅ 修改 module.json5 添加 "2in1" 设备类型
4. ✅ 配置项目签名
5. ✅ 连接鸿蒙 PC 设备
6. ✅ 使用三种方式之一运行应用

八、相关资源

• Flutter HarmonyOS 官方文档^[3]
• DevEco Studio 下载^[4]
• OpenHarmony SDK 文档^[5]

代码已开源,托管在AtomGit 上^[6],欢迎大家下载学习!

如有问题,欢迎在评论区留言讨论。

如果这篇文章对你有帮助，麻烦大家点赞 + 收藏 + 转发三连支持～ 你们的每一份认可，都是我持续输出技术干货的最大动力！后续还会带来更多实操教程，技术解读。记得关注不迷路哦～

也欢迎添加我的联系方式，咱们交个朋友！未来我也会持续分享各类前沿技术干货。