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

本文记录将原来的flutter商城项目在 Windows DevEco Studio 环境下将flutter_shop从「能编译」推进到「首页有数据、登录可用」的完整过程包括环境配置、运行命令、踩坑与最终方案。flutte商城项目源码链接flutter-learn安卓端适配Flutter | 项目打包运行在安卓端一、整体流程概览安装鸿蒙版 Flutter配置无空格路径联接ohos/local.propertiesflutter pub getsetup-harmony-env.bat构建 HAP 并安装网络与首页适配登录本地存储适配阶段目标关键产出环境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、ohpmFlutter OHOS 分支非官方 stable需使用 TPC 提供的flutter_flutterGitflutter pub get拉取依赖建议开启长路径git config --global core.longpaths true2.2 解决「路径含空格」问题核心Windows 上若 Flutter / SDK 安装在D:\Program Files\...Hvigor 拼接flutter.bat时会报D:\Program 不是内部或外部命令做法用目录联接Junction映射到无空格路径并统一使用联接路径。联接路径指向D:\flutter_ohosD:\Program Files\harmony_flutter\flutter_flutter示例D:\deveco_sdkD:\Program Files\Huawei\DevEco Studio\sdk用户环境变量DEVECO_SDK_HOMED:\deveco_sdkPATH 优先使用D:\flutter_ohos\bin避免仍指向D:\Program Files\flutter\bin的官方版 Flutter。2.3 项目内鸿蒙配置ohos/local.properties无空格路径flutter.sdkD:\\flutter_ohos hwsdk.dirD:\\deveco_sdkohos/setup-harmony-env.bat一键设置环境并运行。set DEVECO_SDK_HOMED:\deveco_sdk set PATHD:\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 release3.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 .模拟器内用浏览器访问外网确认模拟器本身能上网电脑端可测 APIInvoke-WebRequest-Urihttps://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与StringJSON 自动解析日志[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 04.4 登录存储鸿蒙专用文件方案文件lib/utils/ohos_login_storage.dart— JSON 写入Directory.systemTemplib/utils/LoginStorage.dart— 检测鸿蒙后走文件存储其它平台仍用shared_preferencesstaticboolget_useOhosFileStorage!kIsWeb(defaultTargetPlatformTargetPlatform.ohos||Platform.operatingSystemohos);测试账号13200000001/123456五、问题与解决方案汇总5.1 构建与环境#现象原因解决方案1DEVECO_SDK_HOME无效未设置或 CMD 用了 PowerShell 语法设D:\deveco_sdk联接 用户环境变量2D:\Program 不是内部或外部命令Program Files空格导致 Hvigor 截断命令local.properties用D:\flutter_ohos必要时改flutter-hvigor-plugin/hvigor_utils.dart用cmd /c3tdesign_flutter编译失败与鸿蒙 Flutter 3.27.5 不兼容移除 TDesign改用 MaterialIcons4module.json5schema 失败写了不支持的network节点删除network块仅保留INTERNET权限5srcPath is not a relative pathPub 缓存绝对路径dependency_overrides: shared_preferences_ohos被注入 hvigor移除该 override登录改用OhosLoginFileStorage6DevFS / 调试 attach 失败鸿蒙调试链路与 Impeller 等优先release可关 Impellerbuildinfo.json55.2 网络与首页#现象原因解决方案7首页永久加载、无数据并发请求挂起 证书校验OhosHttpOverrides 顺序请求 超时与错误 UI8仅有[Dio] GET无200请求未返回同上确认module.json5有INTERNET9模拟器浏览器能上网 App 不行Flutter 网络栈与浏览器不同证书 Overrides 勿依赖并发5.3 登录#现象原因解决方案10MissingPluginException ... 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.propertiesFlutter SDK、DevEco SDK 路径ohos/setup-harmony-env.bat环境变量 运行脚本ohos/entry/src/main/module.json5权限、Abilityohos/entry/src/main/ets/plugins/GeneratedPluginRegistrant.ets原生插件注册当前无第三方插件ohos/hvigorconfig.tsinjectNativeModules读取.flutter-plugins-dependencieslib/main.dartsetupOhosHttpOverrides()lib/utils/ohos_http_overrides.dart鸿蒙 HTTPSlib/utils/DioRequest.dart网络封装lib/pages/Home/home.dart首页顺序加载lib/utils/ohos_login_storage.dart鸿蒙登录态文件存储lib/utils/LoginStorage.dart跨平台存储门面八、经验总结鸿蒙 Flutter 是独立工具链必须用 OHOS 版 FlutterPATH、local.properties、DEVECO_SDK_HOME三者一致。路径规划先于编码Program Files几乎必然在 Hvigor/脚本层踩坑联接目录是性价比最高的解法。网络顺序优于并发首页 5 接口在鸿蒙上顺序调用更稳日志里看到连续200即正常。存储别假设 shared_preferences 可用MissingPluginException用鸿蒙文件存储即可避免绝对路径插件模块。发布模式优先验证setup-harmony-env.bat release更接近真实安装包行为利于排除 DevFS 干扰。配置改动的生效方式module.json5权限、原生插件、HAR 依赖变更 → 需完整重装热重载不够。九、参考链接OpenHarmony TPC flutter_flutterOpenHarmony TPC flutter_packagesHarmonyOS 应用权限列表十、实现效果