一、插件介绍

Hvigor插件是OpenHarmony平台下专为Flutter项目设计的编译工具插件，它通过动态更新项目配置文件（如app.json5、build-profile.json5、oh-package.json5等）的方式，解决了传统手动配置可能导致的版本控制冲突问题。同时，Hvigor插件支持直接依赖插件源码进行构建，让开发者在编写插件时能够直接修改源码并获得代码提示，与Android和iOS平台的开发体验保持一致。

核心优势

1. 动态配置管理：自动更新项目配置文件，避免Git冲突
2. 源码级依赖：支持直接依赖插件源码，提升开发效率
3. 统一开发体验：与Android、iOS平台的开发流程保持一致
4. 产物集中管理：所有编译产物（APP、HAP、HAR等）统一存放在build/ohos目录下

二、环境准备

在使用Hvigor插件前，请确保您的开发环境满足以下要求：

• DevEco Studio 5.0.5+（推荐最新版本）
• JDK 17
• Node.js 16+
• Flutter SDK 3.27.5-ohos-1.0.0+（需从AtomGit获取）

Flutter SDK配置

由于Hvigor插件需要特定版本的Flutter SDK支持，请确保您使用的是支持OpenHarmony平台的Flutter SDK。您可以通过以下方式配置：

# 克隆支持OpenHarmony的Flutter SDK
git clone -b 3.27.5-ohos-1.0.0 https://atomgit.com/openharmony-tpc/flutter_flutter.git

# 配置环境变量
export FLUTTER_HOME=/path/to/flutter_flutter
export PATH=$FLUTTER_HOME/bin:$PATH

# 验证Flutter版本
flutter --version

三、Hvigor插件引入

在Flutter项目中，Hvigor插件是通过项目的ohos目录下的配置文件进行引入的，无需在pubspec.yaml中添加依赖。以下是不同类型项目的具体配置方法：

四、项目配置方法

1. Flutter App项目配置

步骤1：更新.gitignore文件

在ohos/.gitignore文件中进行如下修改：

# 添加以下内容
/package.json
/package-lock.json

# 移除以下内容（如果存在）
# *.har

同时，您可以删除项目中自动生成的har文件夹。

步骤2：修改oh-package.json5文件

在ohos/oh-package.json5文件中移除Flutter相关依赖：

{
  "name": "your_app_name",
  "version": "1.0.0",
  "description": "your_app_description",
  "main": "index.js",
  "author": "your_name",
  "license": "Apache-2.0",
  "dependencies": {
    // 移除 @ohos/flutter_ohos
  },
  "overrides": {
    // 移除 @ohos/flutter_ohos 以及所有flutter插件
  }
}

步骤3：配置hvigorfile.ts

在ohos/hvigorfile.ts文件中添加Hvigor插件：

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：更新entry/oh-package.json5

在ohos/entry/oh-package.json5文件中移除Flutter相关依赖：

{
  "name": "entry",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {
    // 移除 @ohos/flutter_ohos 以及所有flutter插件
  }
}

2. Flutter Module项目配置

Flutter Module项目支持两种集成方式：基于Har产物和基于源码。

基于Har产物方式

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

2. 在host工程的oh-package.json5文件中，添加所有Flutter构建出的har文件：

{
  "name": "host_app",
  "version": "1.0.0",
  "dependencies": {
    // 其他依赖
  },
  "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",
    // 其他Flutter插件的har文件
  }
}

3. （可选）如果项目中插件较多且频繁变动，可以在host工程的hvigorfile.ts中添加以下代码实现动态添加依赖的功能：

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

const directory = '需调整为实际路径' // 例如：./path/flutter_project/build/ohos/har/release
const keyMap = {
  "flutter": "@ohos/flutter_ohos",
  "flutter_embedding_debug": "@ohos/flutter_ohos",
  "flutter_embedding_profile": "@ohos/flutter_ohos",
  "flutter_embedding_release": "@ohos/flutter_ohos",
  "arm64_v8a_debug": "flutter_native_arm64_v8a",
  "arm64_v8a_profile": "flutter_native_arm64_v8a",
  "arm64_v8a_release": "flutter_native_arm64_v8a",
  "x86_64_debug": "flutter_native_x86_64",
  "x86_64_profile": "flutter_native_x86_64",
  "x86_64_release": "flutter_native_x86_64",
  "flutter_module": "@ohos/flutter_module"
}
const rootNode: HvigorNode = getNode(__filename)
rootNode.afterNodeEvaluate(node => {
  const appContext = node.getContext(OhosPluginId.OHOS_APP_PLUGIN) as OhosAppContext
  if (!appContext) {
    return
  }
  const overrides = appContext.getOverrides() ?? {}
  const dependencies = appContext.getDependenciesOpt() ?? {}
  const files = fs.readdirSync(directory);
  const keys = Object.keys(keyMap)
  for (const file of files) {
    if (path.extname(file).toLowerCase() !== '.har') {
      continue
    }
    const fileName = path.parse(file).name
    const depName = keys.includes(fileName) ? keyMap[fileName] : fileName
    const filePath = `file:${path.join(directory, file)}`
    dependencies[depName] = filePath
    overrides[depName] = filePath
  }
  appContext.setDependenciesOpt(dependencies)
  appContext.setOverrides(overrides)
})

export default {
  system: appTasks,
  plugins: []
}

基于源码方式

1. 在host工程下创建或修改hvigorconfig.ts文件：

// 该文件位于flutter module工程.ohos下，需调整为实际路径
import { injectNativeModules, getFlutterProjectPath } from './path/flutter_project/.ohos/include_flutter';

injectNativeModules(__dirname, getFlutterProjectPath(), 1)

2. 在host工程下的hvigorfile.ts中添加flutterHvigorPlugin插件：

import { appTasks } from '@ohos/hvigor-ohos-plugin';
// 该文件位于flutter module工程.ohos下，需调整为实际路径
import { flutterHvigorPlugin, getFlutterProjectPath } from './path/flutter_project/.ohos/include_flutter';

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

3. 在host工程下的build-profile.json5文件中移除flutter_module：

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "artifacts": [
          {
            "type": "HAP",
            "deliveryWithInstall": true,
            "moduleNames": [
              "entry",
              // 移除 "flutter_module"
            ]
          }
        ]
      }
    ]
  }
}

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

3. Flutter Plugin项目配置

注意：对于既有的Flutter Plugin项目，如果不做任何修改仅会导致example无法正常编译，但不影响该plugin在Flutter项目中的正常使用和编译。

可选修改

1. 修改插件项目下的hvigorfile.ts：

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

2. 在插件项目下的oh-package.json5文件中移除@ohos/flutter_ohos依赖：

{
  "name": "your_plugin_name",
  "version": "1.0.0",
  "dependencies": {
    // 移除 @ohos/flutter_ohos
  }
}

必须修改

插件example的调整参考前述的Flutter App项目配置方法。

五、编译验证

完成上述配置后，您可以使用以下命令进行项目编译：

Flutter App项目

# 进入项目根目录
cd your_flutter_app

# 获取依赖
flutter pub get

# 进入ohos目录
cd ohos

# 编译项目
hvigor build --mode=release

Flutter Module项目

# 进入host工程目录
cd host_app

# 进入ohos目录
cd ohos

# 编译项目
hvigor build --mode=release

Flutter Plugin项目

# 进入插件项目根目录
cd your_flutter_plugin

# 获取依赖
flutter pub get

# 进入example的ohos目录
cd example/ohos

# 编译example项目
hvigor build --mode=release

编译成功后，您可以在build/ohos目录下找到生成的产物文件。

六、FAQ

1. 问：为什么要使用Hvigor插件而不是传统的手动配置方式？
   答：传统的手动配置方式需要直接修改项目的配置文件，这可能导致Git冲突。Hvigor插件通过动态更新配置文件的方式，避免了这些冲突，同时提供了更好的开发体验。

2. 问：Hvigor插件支持哪些类型的Flutter项目？
   答：Hvigor插件支持Flutter App、Flutter Module和Flutter Plugin三种类型的项目。

3. 问：使用Hvigor插件后，项目的编译产物在哪里？
   答：所有编译产物（APP、HAP、HAR等）均位于Flutter项目的build/ohos目录下。

4. 问：对于既有项目，使用Hvigor插件需要做哪些调整？
   答：对于既有项目，您需要按照本文档的说明更新.gitignore、oh-package.json5、hvigorfile.ts等文件，并执行flutter pub get命令。

5. 问：Hvigor插件与其他Flutter插件有冲突吗？
   答：Hvigor插件与其他Flutter插件没有冲突，它只是一个编译工具插件，不会影响其他插件的功能。

七、总结

Hvigor插件为OpenHarmony平台下的Flutter项目提供了一种更加高效、便捷的编译方式。通过动态配置管理和源码级依赖支持，它解决了传统编译方式中的诸多问题，提升了开发效率和开发体验。

无论您是开发Flutter App、Flutter Module还是Flutter Plugin，Hvigor插件都能为您提供统一、高效的编译解决方案。希望本文能够帮助您快速上手Hvigor插件，享受更加流畅的Flutter跨平台开发体验。

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