鸿蒙版 Flutter 升级 ohos 构建过程：支持依赖插件源码构建

摘要

本次优化针对鸿蒙版 Flutter 的构建流程进行了全面改进。通过引入 Hvigor 插件实现动态配置更新，消除因频繁修改配置文件引发的冲突。同时，支持直接依赖插件源码构建，提升插件开发体验，使其与 Android 和 iOS 平台保持一致。调整后，构建产物统一存放于 flutter 项目的 build/ohos 目录。既有项目需手动调整方可适配新流程。

前言

在鸿蒙版 Flutter 开发过程中，我们曾面临两大挑战：一是配置文件的频繁修改易导致提交冲突，二是插件开发时缺乏代码提示。为解决这些问题，本次更新引入了 Hvigor 插件，实现动态配置更新，并支持直接依赖插件源码进行构建，显著提升开发体验。

一、对于 flutter app 项目

背景说明

由于构建产物位置变更，需对项目配置进行相应调整，以适配新的构建流程。

具体步骤

1. **调整 .gitignore 文件**

在 ohos/.gitignore 中添加以下内容：

/package.json
/package-lock.json

同时移除：

*.har

对应的项目里自动生成的 har 文件夹也可以直接删除。

2. **修改 oh-package.json5 文件**

移除 ohos/oh-package.json5 中 dependencies 的 @ohos/flutter_ohos，以及 overrides 中的 @ohos/flutter_ohos 和 flutter 插件。

3. **添加 Hvigor 插件**

在 ohos/hvigorfile.ts 中添加 Hvigor 插件 flutterHvigorPlugin，代码如下：

import path from 'path'
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { flutterHvigorPlugin } from 'flutter-hvigor-plugin';

export default {
    system: appTasks,
    plugins:[flutterHvigorPlugin(path.dirname(__dirname))]
}

4. **创建 hvigorconfig.ts 文件**

添加 ohos/hvigorconfig.ts 文件，内容如下：

import path from 'path'
import { injectNativeModules } from 'flutter-hvigor-plugin';

injectNativeModules(__dirname, path.dirname(__dirname))

5. **修改 entry/hvigorfile.ts 文件**

修改 ohos/entry/hvigorfile.ts 文件为：

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
export default {
    system: hapTasks,
    plugins: []
}

6. **更新 oh-package.json5 文件**

移除 ohos/entry/oh-package.json5 中 dependencies 的 @ohos/flutter_ohos 以及 flutter 插件。

二、对于 flutter module 项目

基于 Har 产物

1. **移除 flutter 相关依赖**

在 host 工程下 oh-package.json5 中移除 dependencies 和 overrides 中的 flutter 相关依赖（如不存在则无需处理）。

2. **添加 Har 产物路径**

在 host 工程下 oh-package.json5 的 overrides 中添加所有 flutter 构建出的 har 产物路径，例如：

"overrides": {
    "@ohos/flutter_ohos": "file:./path/flutter_project/build/ohos/har/release/flutter.har",
    "@ohos/flutter_module": "file:./path/flutter_project/build/ohos/har/release/flutter_module.har",
    "plugin_x": "file:./path/flutter_project/build/ohos/har/release/plugin_x.har",
}

当项目中插件较多且有变动时，可在 host 工程的 hvigorfile.ts 中添加以下代码实现动态添加 overrides：

import fs from 'fs'
import path from 'path'
import { OhosPluginId } from '@ohos/hvigor-ohos-plugin';
import { getNode, hvigor } from '@ohos/hvigor'

const directory = '替换为 har 产物目录路径'
const rootNode = getNode(__filename)
rootNode.afterNodeEvaluate(node => {
  const appContext = node.getContext(OhosPluginId.OHOS_APP_PLUGIN) as OhosAppContext
  let overrides = appContext.getOverrides() ?? {}
  const files = fs.readdirSync(directory)
  for (const file of files) {
    if (path.extname(file).toLowerCase() !== '.har') {
      continue
    }
    let depName = path.parse(file).name
    switch (depName) {
      case 'flutter':
        depName = '@ohos/flutter_ohos'
        break
      case 'flutter_module':
        depName = '@ohos/flutter_module'
        break
    }
    overrides[depName] = `file:${path.join(directory, file)}`
  }
  appContext.setOverrides(overrides)
})

3. **添加依赖**

在 entry（或其他 hap 模块）的 oh-package.json5 的 dependencies 中添加以下依赖：

"dependencies": {
    "@ohos/flutter_ohos": "",
    "@ohos/flutter_module": "",
}

如果本模块直接使用了某些 Flutter 插件中的 API，则需添加相应插件的依赖，例如：

"dependencies": {
    ...
    "plugin_x": ""
}

基于源码

1. **配置 hvigorconfig.ts 文件**

在 host 工程下创建或修改 hvigorconfig.ts 文件（如果没有需新建），添加以下代码：

import { injectNativeModules, getFlutterProjectPath } from './path/flutter_project/.ohos/include_flutter';

injectNativeModules(__dirname, getFlutterProjectPath(), 1)

2. **更新 hvigorfile.ts 文件**

在 host 工程下的 hvigorfile.ts 中添加 flutterHvigorPlugin 插件，代码如下：

import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { flutterHvigorPlugin, getFlutterProjectPath } from './path/flutter_project/.ohos/include_flutter';

export default {
  system: appTasks,
  plugins:[flutterHvigorPlugin(getFlutterProjectPath(), 1)]
}

3. **移除 flutter_module**

在 host 工程下 build-profile.json5 中移除 flutter_module。

4. **移除 flutter 相关依赖**

在 host 工程下 oh-package.json5 中移除 dependencies 和 overrides 中的 flutter 相关依赖（如不存在则无需处理）。

5. **添加依赖**

在 entry（或其他 hap 模块）的 oh-package.json5 的 dependencies 中添加以下依赖：

"dependencies": {
    "@ohos/flutter_ohos": "",
    "@ohos/flutter_module": "",
}

如果本模块直接使用了某些 Flutter 插件中的 API，则需添加相应插件的依赖，例如：

"dependencies": {
    ...
    "plugin_x": ""
}

三、对于 flutter plugin 项目

可选修改

1. **更新 hvigorfile.ts 文件**

将插件项目下的 hvigorfile.ts 改为：

import { harTasks } from '@ohos/hvigor-ohos-plugin';
export default {
    system: harTasks,
    plugins: []
}

2. **移除 dependencies**

在插件项目下 oh-package.json5 中移除 dependencies 的 @ohos/flutter_ohos。

必须修改

插件 example 的调整请参考前述的 flutter app 项目部分。

总结

本次鸿蒙版 Flutter 优化 ohos 构建过程，通过引入 Hvigor 插件实现了动态配置更新，有效避免了配置文件频繁修改引发的提交冲突。同时，支持直接依赖插件源码进行构建，极大地提升了插件开发体验，使其与 Android 和 iOS 平台保持一致。调整后，构建产物统一存放于 flutter 项目的 build/ohos 目录下。对于既有项目，需按照上述步骤手动调整，调整完成后执行 flutter pub get 即可。大家可关注相关 pr，待其合并后，便可以按照这种方式进行构建。

坚果派

坚果派由坚果等人创建，团队拥有若干华为HDE，以及若干其他领域的三十余位万粉博主运营。专注于分享的技术包括HarmonyOS/OpenHarmony，ArkUI-X，元服务，服务卡片，华为自研语言，BlueOS操作系统、团队成员聚集在北京、上海、广州、深圳、南京、杭州、苏州、宁夏等地。 聚焦“鸿蒙原生应用”、“智能物联”和“AI赋能”、“人工智能”四大业务领域，依托华为开发者专家等强大的技术团队，以及涵盖需求、开发、测试、运维于一体的综合服务体系，赋能文旅、媒体、社交、家居、消费电子等行业客户，满足社区客户数字化升级转型的需求，帮助客户实现价值提升。 目前上架鸿蒙原生应用18款，三方库72个。

地址：https://atomgit.com/nutpi

https://gitcode.com/nutpi