[Flutter-OH]Flutter 3.35 For HarmonyOS | 如何正确地使用第三方库（避免 hvigor srcPath 绝对路径报错）

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

本文示例代码已托管至 AtomGit，仓库地址： https://atomgit.com/HMYoung/hmosdemo

开发环境

补充说明一点：HarmonyOS 模拟器目前必须选 API 21 才能跑起来，低版本的模拟器会直接卡在部署阶段，这个坑不少人踩过。

一、问题现象

执行flutter run构建 HAP 阶段报错：

hvigor ERROR: AdaptorError 00303231 Configuration Error Error Message: The srcPath is not a relative path: C:/Users/xxx/AppData/Local/Pub/Cache/git/flutter_packages-xxxx/packages/shared_preferences/shared_preferences_ohos/ohos

核心报错是这一句：

The srcPath is not a relative path

图1：hvigor srcPath 绝对路径报错

二、问题本质

HarmonyOS 用的是 OpenHarmony 生态的 Hvigor 构建系统，它对srcPath有一条死规定：

srcPath 必须是相对路径，绝对路径直接报错，没有任何例外。

当我们在pubspec.yaml里写 git 依赖时：

dependencies: shared_preferences: git: url: "https://gitcode.com/openharmony-tpc/flutter_packages.git" path: "packages/shared_preferences/shared_preferences"

Flutter 会把插件 clone 到 Pub Cache 下：

C:/Users/xxx/AppData/Local/Pub/Cache/git/flutter_packages-xxxx/

这是绝对路径。Harmony Flutter 适配层生成hvigorconfig.ts时会把这个路径原样写进去，构建就挂了。

三、很多人忽略的关键点

改成 path 依赖之后，仍然可能报同样的错，原因在这里。

即便项目里已经改成：

dependencies: shared_preferences: path: packages/shared_preferences/shared_preferences

打开packages/shared_preferences/shared_preferences/pubspec.yaml，里面默认还是：

dependencies: shared_preferences_ohos: git: url: https://gitee.com/openharmony-sig/flutter_packages.git

依赖链是：

你的项目 └── shared_preferences（path，没问题） └── shared_preferences_ohos（git，问题在这）

shared_preferences_ohos还是从 git 拉，还是绝对路径，报错照样触发。这一层很容易被忽略。

四、插件源码从哪来

方式一（常用）：从 Pub Cache 直接拿

只要之前用 git 方式跑过一次，Flutter 已经把插件下载到本地了：

C:/Users/xxx/AppData/Local/Pub/Cache/git/flutter_packages-xxxx/

进到packages/shared_preferences/，能看到：

shared_preferences/ shared_preferences_ohos/ shared_preferences_android/

把整个packages/shared_preferences/这一层复制到你的工程里，放到packages/目录下。注意不能只复制最内层的shared_preferences/，外面那层目录也要带上。

方式二：直接从仓库克隆

git clone https://gitcode.com/openharmony-tpc/flutter_packages.git

从flutter_packages/packages/shared_preferences/拷贝到工程的packages/目录里。

五、正确的工程结构

项目根目录/ │ ├── pubspec.yaml ├── lib/ │ └── main.dart └── packages/ └── shared_preferences/ ├── shared_preferences/ │ └── pubspec.yaml ← 这个文件需要改 ├── shared_preferences_ohos/ │ └── pubspec.yaml └── shared_preferences_android/ └── pubspec.yaml

六、改插件内部的依赖

打开packages/shared_preferences/shared_preferences/pubspec.yaml，把：

dependencies: shared_preferences_ohos: git: url: https://gitee.com/openharmony-sig/flutter_packages.git

改成：

dependencies: shared_preferences_ohos: path: ../shared_preferences_ohos

这一步不改的话，Flutter 还是会去走 git，绝对路径问题照样存在。

七、改项目根 pubspec.yaml

dependencies: flutter: sdk: flutter ​ shared_preferences: path: packages/shared_preferences/shared_preferences

八、清缓存

这步不能省，旧缓存会让改动不生效：

flutter clean

然后手动删掉这几个目录和文件：

.dart_tool/ build/ pubspec.lock ohos/.hvigor/

之后重新跑：

flutter pub get flutter run

九、验证

检查 pubspec.lock

flutter pub get完成后，打开pubspec.lock，找shared_preferences_ohos这一段：

shared_preferences_ohos: dependency: transitive description: path: "../shared_preferences_ohos" relative: true source: path version: "x.x.x"

source: path且relative: true就对了。如果还是source: git，说明哪步没改到位，回头检查一下插件内部的 pubspec.yaml。

设备运行截图

图2：Flutter 应用在 HarmonyOS 6.0.0.328 设备上成功运行

十、问题ISSUE

这里有问题ISSUE:

https://gitcode.com/openharmony-tpc/flutter_packages/issues/621

其他的解决方案，可选下面其中一个:
1.把代码放到C盘能暂时解决问题。
2.PUB_CACHE修改为和代码仓库相同盘，让pub依赖下载到和代码一样的盘内

十一、为什么 Hvigor 要求相对路径

Hvigor 是 OpenHarmony 的官方构建工具，定位类似 Android 的 Gradle。hvigorconfig.ts里所有模块的srcPath必须是相对于工程根目录的路径，原因主要有三点：

一是可移植性。绝对路径和本机环境绑死了，换台机器或者上 CI 就跑不了，相对路径则不存在这个问题。

二是访问控制。限制在工程目录内，防止构建脚本越界访问系统其他位置的文件。

三是产物一致性。HAP 包里不能掺入任何跟特定机器相关的路径信息。

十二、总结

操作步骤回顾：

1. 从 Pub Cache 或 git clone 获取插件，拷到工程packages/目录

2. 改插件内部pubspec.yaml，git 依赖换成 path 相对路径

3. 改项目根pubspec.yaml，对应插件改为 path 依赖

4. flutter clean，手动删.dart_tool、build、pubspec.lock、ohos/.hvigor

5. flutter pub get然后flutter run

6. 确认pubspec.lock里source: path

本文示例代码已托管至 AtomGit，欢迎参考： https://atomgit.com/HMYoung/hmosdemo

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net