Flutter应用运行到鸿蒙PC指南

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

前置准备

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

一、检查开发环境

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

bash 复制代码

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 创建新项目

bash 复制代码

flutter create my_app
cd 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" 设备类型:

json5 复制代码

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

说明:

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

3.2 项目签名配置

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

步骤1: 打开DevEco Studio

在DevEco Studio中打开项目。

步骤2: 配置签名

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

步骤3: 验证签名

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

四、连接鸿蒙PC设备

4.1 查看已连接的设备

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

bash 复制代码

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直接运行到指定设备:

bash 复制代码

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

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

优点:

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

方式二: 编译HAP包后安装

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

步骤1: 编译HAP包

bash 复制代码

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

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

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

步骤2: 使用HDC工具安装

bash 复制代码

# 安装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中直接运行:

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

优点:

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

六、常见问题

Q1: 提示"Unable to locate device"

解决方案:

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

Q2: 签名失败

解决方案:

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

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

解决方案:

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

Q4: 编译速度慢

解决方案:

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

七、总结

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

关键步骤回顾:

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

八、相关资源

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

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