当前位置：首页 > news >正文

Flutter | 商城项目鸿蒙（OpenHarmony）适配实战

news 2026/6/17 16:05:27

本文记录将原来的flutter商城项目在 Windows + DevEco Studio 环境下，将flutter_shop从「能编译」推进到「首页有数据、登录可用」的完整过程，包括环境配置、运行命令、踩坑与最终方案。
flutte商城项目源码链接：flutter-learn
安卓端适配：Flutter | 项目打包运行在安卓端

一、整体流程概览

阶段	目标	关键产出
环境	SDK、hvigor、ohpm 可用	`DEVECO_SDK_HOME`、`D:\flutter_ohos`
构建	`assembleHap`成功	`build/ohos/hap/entry-default-signed.hap`
运行	模拟器安装并启动	`flutter run --release -d 127.0.0.1:5555`
业务	首页加载、登录持久化	`ohos_http_overrides`、`OhosLoginFileStorage`

二、环境准备

2.1 必备软件

组件	说明
DevEco Studio	提供 HarmonyOS SDK、模拟器、hvigor、ohpm
Flutter OHOS 分支	非官方 stable，需使用 TPC 提供的`flutter_flutter`
Git	`flutter pub get`拉取依赖；建议开启长路径：`git config --global core.longpaths true`

2.2 解决「路径含空格」问题（核心）

Windows 上若 Flutter / SDK 安装在D:\Program Files\...，Hvigor 拼接flutter.bat时会报：

'D:\Program' 不是内部或外部命令

做法：用目录联接（Junction）映射到无空格路径，并统一使用联接路径。

联接路径	指向
`D:\flutter_ohos`	`D:\Program Files\harmony_flutter\flutter_flutter`（示例）
`D:\deveco_sdk`	`D:\Program Files\Huawei\DevEco Studio\sdk`

用户环境变量：

DEVECO_SDK_HOME=D:\deveco_sdk

PATH 优先使用：D:\flutter_ohos\bin（避免仍指向D:\Program Files\flutter\bin的官方版 Flutter）。

2.3 项目内鸿蒙配置

ohos/local.properties（无空格路径）：

flutter.sdk=D:\\flutter_ohos hwsdk.dir=D:\\deveco_sdk

ohos/setup-harmony-env.bat：一键设置环境并运行。

set DEVECO_SDK_HOME=D:\deveco_sdk set "PATH=D:\flutter_ohos\bin;...hvigor...;...ohpm...;%PATH%" cd /d %~dp0.. flutter run --release -d 127.0.0.1:5555 REM release 模式

模式	命令	说明
调试	`setup-harmony-env.bat`	支持热重载，可能遇 DevFS 问题
发布	`setup-harmony-env.bat release`	推荐；稳定，日志见`hilog`/ 控制台

2.4 网络权限（module.json5）

在ohos/entry/src/main/module.json5中声明：

"requestPermissions": [ { "name": "ohos.permission.INTERNET", ... }, { "name": "ohos.permission.GET_NETWORK_INFO", ... } ]

注意：勿在module下添加"network": { "cleartextTraffic": true }。当前 SDK 的 schema不支持该字段，会导致hvigor校验失败（property name must be valid）。本项目 API 为 HTTPS，无需明文流量配置。

三、构建与运行步骤

3.1 首次 / 大改后建议流程

cd /d E:\fairy\flutter-learn\project\flutter_shop D:\flutter_ohos\bin\flutter clean D:\flutter_ohos\bin\flutter pub get cd ohos setup-harmony-env.bat release

3.2 成功标志

终端：√ Built build\ohos\hap\entry-default-signed.hap
日志：installing hap. bundleName: com.example.flutter_shop
首页日志：

3.3 常用排错命令

D:\flutter_ohos\bin\flutter doctor D:\flutter_ohos\bin\flutter devices

必须配置好鸿蒙环境后才能运行

配置完环境后，运行

flutter create .

模拟器内用浏览器访问外网，确认模拟器本身能上网；电脑端可测 API：

Invoke-WebRequest-Uri"https://meikou-api.itheima.net/home/banner"-UseBasicParsing

四、业务层鸿蒙适配（Dart）

官方shared_preferences的pubspec未声明ohos平台，且鸿蒙上不宜强行接入 TPC 的shared_preferences_ohos（见下文构建问题）。因此网络与存储均在Dart 层做了针对性适配。

4.1 入口：HTTPS 全局配置

文件：lib/utils/ohos_http_overrides.dart
调用：lib/main.dart→setupOhosHttpOverrides()

voidmain(){setupOhosHttpOverrides();runApp(getRootWidget());}

作用：

在Platform.operatingSystem == 'ohos'时注册HttpOverrides
设置连接超时、开发阶段badCertificateCallback（浏览器能开、Flutter 请求失败时常见）

4.2 网络请求：Dio

文件：lib/utils/DioRequest.dart

要点	说明
超时	connect/send/receive 均为 12s，外层`Future.timeout`兜底
响应	支持`Map`与`String`JSON 自动解析
日志	`[Dio] GET/POST ...`与`[Dio] 200 ...`便于模拟器排错

4.3 首页：顺序请求 + 错误展示

文件：lib/pages/Home/home.dart

问题	原因	方案
一直转圈	5 个接口`Future.wait`并发，鸿蒙 HTTPS 易挂起	`TargetPlatform.ohos`时改为顺序请求
无错误提示	请求未结束，`catch`不执行	整页`25s`超时 + 红色错误条 + 下拉刷新
重复请求 recommend	首屏`maxScrollExtent == 0`触发滚动监听	增加`_homeDataReady`、判断`maxScrollExtent > 0`

4.4 登录存储：鸿蒙专用文件方案

文件：

lib/utils/ohos_login_storage.dart— JSON 写入Directory.systemTemp
lib/utils/LoginStorage.dart— 检测鸿蒙后走文件存储，其它平台仍用shared_preferences

staticboolget_useOhosFileStorage=>!kIsWeb&&(defaultTargetPlatform==TargetPlatform.ohos||Platform.operatingSystem=='ohos');

测试账号：13200000001/123456

五、问题与解决方案汇总

5.1 构建与环境

#	现象	原因	解决方案
1	`DEVECO_SDK_HOME`无效	未设置或 CMD 用了 PowerShell 语法	设`D:\deveco_sdk`联接 + 用户环境变量
2	`'D:\Program' 不是内部或外部命令`	`Program Files`空格导致 Hvigor 截断命令	`local.properties`用`D:\flutter_ohos`；必要时改`flutter-hvigor-plugin`/`hvigor_utils.dart`用`cmd /c`
3	`tdesign_flutter`编译失败	与鸿蒙 Flutter 3.27.5 不兼容	移除 TDesign，改用 Material`Icons`
4	`module.json5`schema 失败	写了不支持的`"network"`节点	删除`network`块，仅保留`INTERNET`权限
5	`srcPath is not a relative path`（Pub 缓存绝对路径）	`dependency_overrides: shared_preferences_ohos`被注入 hvigor	移除该 override；登录改用`OhosLoginFileStorage`
6	DevFS / 调试 attach 失败	鸿蒙调试链路与 Impeller 等	优先`release`；可关 Impeller（`buildinfo.json5`）

5.2 网络与首页

#	现象	原因	解决方案
7	首页永久加载、无数据	并发请求挂起 + 证书校验	`OhosHttpOverrides`+ 顺序请求 + 超时与错误 UI
8	仅有`[Dio] GET`无`200`	请求未返回	同上；确认`module.json5`有`INTERNET`
9	模拟器浏览器能上网 App 不行	Flutter 网络栈与浏览器不同	证书 Overrides + 勿依赖并发

5.3 登录

#	现象	原因	解决方案
10	`MissingPluginException ... shared_preferences`	默认走`MethodChannel`，鸿蒙无实现	`OhosLoginFileStorage`，不注册`shared_preferences_ohos`原生模块
11	登录 API 200 仍 Toast 报错	保存 Token 时插件崩溃	同上；接口成功后的失败仅在存储环节

六、依赖与插件策略

6.1 当前`pubspec.yaml`要点

dependencies:dio:^5.9.2shared_preferences:^2.2.2# 非鸿蒙平台使用carousel_slider:^5.1.2# 已移除 tdesign_flutter

不要为修登录而添加：

# 不推荐 — 会导致 hvigor srcPath 绝对路径错误dependency_overrides:shared_preferences_ohos:git:...

.flutter-plugins-dependencies中"ohos": []为健康状态。

6.2 若未来要接入更多原生插件

优先查 OpenHarmony TPC flutter_packages 是否有*_ohos实现
插件模块srcPath必须是相对工程 ohos 目录的路径，不能是 Pub 缓存绝对路径
改module.json5/ 插件后需flutter clean+ 重装 HAP
能用纯 Dart 方案（文件、内存）的，优先纯 Dart，减少 Hvigor 模块复杂度

七、关键文件清单

路径	作用
`ohos/local.properties`	Flutter SDK、DevEco SDK 路径
`ohos/setup-harmony-env.bat`	环境变量 + 运行脚本
`ohos/entry/src/main/module.json5`	权限、Ability
`ohos/entry/src/main/ets/plugins/GeneratedPluginRegistrant.ets`	原生插件注册（当前无第三方插件）
`ohos/hvigorconfig.ts`	`injectNativeModules`读取`.flutter-plugins-dependencies`
`lib/main.dart`	`setupOhosHttpOverrides()`
`lib/utils/ohos_http_overrides.dart`	鸿蒙 HTTPS
`lib/utils/DioRequest.dart`	网络封装
`lib/pages/Home/home.dart`	首页顺序加载
`lib/utils/ohos_login_storage.dart`	鸿蒙登录态文件存储
`lib/utils/LoginStorage.dart`	跨平台存储门面

八、经验总结

鸿蒙 Flutter 是独立工具链：必须用 OHOS 版 Flutter，PATH、local.properties、DEVECO_SDK_HOME三者一致。
路径规划先于编码：Program Files几乎必然在 Hvigor/脚本层踩坑，联接目录是性价比最高的解法。
网络：顺序优于并发：首页 5 接口在鸿蒙上顺序调用更稳；日志里看到连续200即正常。
存储：别假设 shared_preferences 可用：MissingPluginException用鸿蒙文件存储即可，避免绝对路径插件模块。
发布模式优先验证：setup-harmony-env.bat release更接近真实安装包行为，利于排除 DevFS 干扰。
配置改动的生效方式：module.json5权限、原生插件、HAR 依赖变更 → 需完整重装，热重载不够。