本文记录将原来的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()

void main() {
  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

static bool get _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.2
  shared_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 若未来要接入更多原生插件

1. 优先查 OpenHarmony TPC flutter_packages 是否有 *_ohos 实现
2. 插件模块 srcPath 必须是 相对工程 ohos 目录 的路径，不能是 Pub 缓存绝对路径
3. 改 module.json5 / 插件后需 flutter clean + 重装 HAP
4. 能用纯 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	跨平台存储门面

---

八、经验总结

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

---

九、参考链接

• OpenHarmony TPC flutter_flutter
• OpenHarmony TPC flutter_packages
• HarmonyOS 应用权限列表

---

十、实现效果