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

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

---

开发环境

项目	版本
Flutter	3.35 (OHOS 分支)
HarmonyOS	6.0.0.328
DevEco Studio	建议配套版本
模拟器 API	API 21（低于此版本无法运行）

补充说明一点：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 设备上成功运行

---

十、其他常用 OHOS 插件

同样的问题在其他插件上也会出现，处理方式完全一样：

插件	OHOS 平台包	内部 path 改法
shared_preferences	shared_preferences_ohos	path: ../shared_preferences_ohos
path_provider	path_provider_ohos	path: ../path_provider_ohos
connectivity_plus	connectivity_plus_ohos	path: ../connectivity_plus_ohos
image_picker	image_picker_ohos	path: ../image_picker_ohos
camera	camera_ohos	path: ../camera_ohos

步骤都一样：拷插件到 packages/，改插件内部 pubspec.yaml，改项目根 pubspec.yaml，清缓存重跑。

---

十一、为什么 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