08. Flutter鸿蒙资源与依赖管理：图片、字体、pubspec和oh-package配置

Flutter 鸿蒙项目里同时存在 Flutter 资源体系和鸿蒙工程资源体系。图片、字体、Dart 包通常走 pubspec.yaml；鸿蒙原生侧依赖和资源则在 ohos 工程中处理。两套体系分清楚，资源加载和依赖升级会稳定很多。

Flutter 资源目录

assets
├─ images
│  ├─ banner.png
│  └─ avatar.png
└─ fonts
   └─ HarmonyText.ttf

资源目录放项目根目录，路径尽量使用英文和小写。图片命名不要包含空格，避免不同平台解析路径时出现问题。

声明图片

flutter:
  uses-material-design: true
  assets:
    - assets/images/

使用：

Image.asset(
  'assets/images/banner.png',
  width: double.infinity,
  height: 180,
  fit: BoxFit.cover,
)

如果运行时报 Unable to load asset，优先检查 pubspec.yaml 缩进、资源路径、文件名大小写，然后执行 flutter pub get。

声明字体

flutter:
  fonts:
    - family: HarmonyText
      fonts:
        - asset: assets/fonts/HarmonyText.ttf

使用：

const Text(
  'Flutter 鸿蒙项目',
  style: TextStyle(
    fontFamily: 'HarmonyText',
    fontSize: 22,
    fontWeight: FontWeight.w600,
  ),
)

Flutter 依赖

添加 Dart 包：

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.2

执行：

flutter pub get

查看依赖树：

flutter pub deps

鸿蒙侧依赖边界

oh-package.json5 属于鸿蒙侧依赖体系。后续如果写 ArkTS 插件、接原生模块、嵌入原生组件，就会遇到鸿蒙侧依赖配置。不要把鸿蒙包写进 pubspec.yaml，也不要把 Dart 包写进 oh-package.json5。

资源或依赖变更后的通用处理：

flutter clean
flutter pub get
flutter run --debug

资源缓存问题

图片或字体已经添加，但页面仍然显示旧内容时，通常是缓存或声明没有刷新。可以按顺序处理：

flutter pub get
flutter clean
flutter run --debug

如果是图片路径问题，控制台一般会出现 Unable to load asset。这时先检查文件是否真实存在，再检查 pubspec.yaml 缩进，不要一上来就怀疑鸿蒙侧配置。

三方包兼容性

不是所有 Flutter 三方包都已经适配 OpenHarmony。选择依赖时要看它是否包含 ohos 平台实现，尤其是涉及相机、定位、蓝牙、地图、播放器、WebView、传感器等原生能力的包。

排查依赖来源：

flutter pub deps
flutter pub outdated

如果某个包在 Android 或 iOS 正常，但鸿蒙构建失败，优先检查该包是否有 ohos 目录或对应 OpenHarmony 适配版本。

pubspec 缩进检查

pubspec.yaml 对缩进敏感。资源不生效时，先看缩进：

flutter:
  uses-material-design: true
  assets:
    - assets/images/
  fonts:
    - family: HarmonyText
      fonts:
        - asset: assets/fonts/HarmonyText.ttf

assets 和 fonts 都在 flutter 下面，不能和 dependencies 平级写错。

依赖升级策略

升级三方包前先查看当前依赖：

flutter pub outdated
flutter pub deps

升级后执行：

flutter clean
flutter pub get
flutter run --debug

如果某个包还没有适配 OpenHarmony，可能在普通 Flutter 平台可用，但鸿蒙构建失败。遇到这类问题，要优先查该包是否提供 ohos 平台实现。
`

升级后执行：

flutter clean
flutter pub get
flutter run --debug

如果某个包还没有适配 OpenHarmony，可能在普通 Flutter 平台可用，但鸿蒙构建失败。遇到这类问题，要优先查该包是否提供 ohos 平台实现。