前言欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net从这篇开始正式进入 OpenHarmony 适配的核心内容。第一步是搭建插件工程——创建ohos目录、配置各种 json5 文件、写好入口导出。这些看起来是脚手架工作但配置错一个字段就可能导致插件加载失败排查起来非常痛苦。一、ohos 目录结构1.1 完整目录树flutter_web_auth/ ├── lib/ # Dart 源码 ├── android/ # Android 插件 ├── ios/ # iOS 插件 ├── macos/ # macOS 插件 ├── ohos/ # OpenHarmony 插件 │ ├── src/ │ │ └── main/ │ │ ├── ets/ │ │ │ └── components/ │ │ │ └── plugin/ │ │ │ └── FlutterWebAuthPlugin.ets ← 核心实现 │ │ └── module.json5 ← 模块声明 │ ├── build-profile.json5 ← 构建配置 │ ├── hvigorfile.ts ← 构建脚本 │ ├── index.ets ← 入口导出 │ ├── oh-package.json5 ← 包配置 │ └── .gitignore ← Git 忽略 ├── pubspec.yaml # Flutter 包配置 └── example/ # 示例应用1.2 各文件职责二、oh-package.json5 包配置2.1 完整内容{ name: flutter_web_auth, version: 1.0.0, description: Please describe the basic information., main: index.ets, author: , license: Apache-2.0, dependencies: {} }2.2 字段说明字段值说明nameflutter_web_auth包名必须与 pubspec.yaml 中的 name 一致version1.0.0OpenHarmony 包版本mainindex.ets入口文件路径licenseApache-2.0许可证dependencies{}无额外依赖2.3 与 pubspec.yaml 的对应# pubspec.yamlname:flutter_web_authversion:0.6.0// oh-package.json5 name: flutter_web_auth, // 必须一致 version: 1.0.0, // 可以不同name 必须一致否则 Flutter-OHOS 框架找不到插件。version 可以独立管理。三、build-profile.json5 构建配置3.1 完整内容{ apiType: stageMode, targets: [ { name: default, runtimeOS: OpenHarmony } ] }3.2 字段说明字段值说明apiTypestageModeStage 模型当前标准targets.namedefault默认构建目标targets.runtimeOSOpenHarmony目标操作系统3.3 Stage 模型 vs FA 模型模型状态说明Stage 模型当前标准Flutter-OHOS 使用FA 模型已废弃早期 HarmonyOS所有 Flutter-OHOS 插件都使用 Stage 模型。如果你看到 FA 模型的教程那是过时的。四、module.json5 模块声明4.1 完整内容{ module: { name: flutter_web_auth, type: har, deviceTypes: [ default, tablet ] } }4.2 字段说明字段值说明nameflutter_web_auth模块名称typeharHARHarmonyOS Archive类型deviceTypesdefault, tablet支持的设备类型4.3 模块类型类型说明用途har静态共享包Flutter 插件使用hap应用包可安装的应用hsp动态共享包运行时加载4.4 与 secure_application 的对比// flutter_web_auth 的 module.json5 { module: { name: flutter_web_auth, type: har, deviceTypes: [default, tablet] } } // secure_application 的 module.json5完全相同的结构 { module: { name: secure_application, type: har, deviceTypes: [default, tablet] } }所有 Flutter-OHOS 插件的 module.json5 结构都一样只有 name 不同。五、index.ets 入口文件5.1 完整内容importFlutterWebAuthPluginfrom./src/main/ets/components/plugin/FlutterWebAuthPlugin;exportdefaultFlutterWebAuthPlugin;5.2 作用index.ets 是 oh-package.json5 中main字段指向的文件。Flutter-OHOS 框架通过这个文件找到插件类。5.3 导入路径index.ets ↓ import from ./src/main/ets/components/plugin/FlutterWebAuthPlugin.ets ↓ export default FlutterWebAuthPlugin 类5.4 常见错误错误症状解决路径拼写错误插件加载失败检查文件路径是否正确没有 export default框架找不到类确保 export default类名不匹配注册失败确保与 pubspec.yaml 中的 pluginClass 一致六、hvigorfile.ts 构建脚本6.1 完整内容import{harTasks}fromohos/hvigor-ohos-plugin;exportdefault{system:harTasks,plugins:[]}6.2 作用hvigorfile.ts 是 Hvigor 构建系统的配置文件类似 Android 的 build.gradle。对于 Flutter 插件使用默认的harTasks就够了。七、.gitignore 配置7.1 完整内容/node_modules /oh_modules /build /oh-package-lock.json5 /.preview7.2 说明路径说明node_modulesNode.js 依赖Hvigor 使用oh_modulesOpenHarmony 模块依赖build构建输出oh-package-lock.json5依赖锁定文件.preview预览缓存八、pubspec.yaml 中的 ohos 平台声明8.1 配置flutter:plugin:platforms:android:package:com.linusu.flutter_web_authpluginClass:FlutterWebAuthPluginohos:package:com.linusu.flutter_web_authpluginClass:FlutterWebAuthPluginios:pluginClass:FlutterWebAuthPluginmacos:pluginClass:FlutterWebAuthPluginweb:pluginClass:FlutterWebAuthWebfileName:flutter_web_auth_web.dart8.2 ohos 平台字段字段值说明packagecom.linusu.flutter_web_auth包名与 Android 相同pluginClassFlutterWebAuthPluginArkTS 类名8.3 与其他插件的对比插件需要 package需要 fileNameflutter_web_auth✅❌secure_application❌✅flutter_speech✅❌不同插件的 ohos 平台配置方式不完全一样。有的需要 package有的需要 fileName取决于 Flutter-OHOS 框架的版本和插件的注册方式。九、工程搭建检查清单9.1 文件检查ohos/oh-package.json5存在且 name 正确ohos/build-profile.json5存在且 apiType 为 stageModeohos/src/main/module.json5存在且 type 为 harohos/index.ets存在且导出路径正确ohos/hvigorfile.ts存在ohos/src/main/ets/components/plugin/FlutterWebAuthPlugin.ets存在9.2 配置一致性检查oh-package.json5 的 name 与 pubspec.yaml 的 name 一致pubspec.yaml 中 ohos.pluginClass 与 ArkTS 类名一致index.ets 的 import 路径指向正确的文件9.3 常见搭建错误错误原因解决插件未被识别pubspec.yaml 缺少 ohos 平台添加 ohos 配置编译失败module.json5 格式错误检查 json5 语法类找不到index.ets 导出路径错误修正 import 路径注册失败pluginClass 名称不匹配确保名称一致总结本文详细讲解了 flutter_web_auth 的 OpenHarmony 插件工程搭建目录结构标准的 ohos/ 目录布局6个关键文件oh-package.json5包名必须与 pubspec.yaml 一致module.json5type 为 har支持 default 和 tabletindex.ets入口导出路径必须正确pubspec.yamlohos 平台声明 pluginClass下一篇我们讲 FlutterPlugin 与 AbilityAware 双接口实现——flutter_web_auth 为什么需要 AbilityAware。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源OpenHarmony HAR 包开发oh-package.json5 规范module.json5 配置Flutter-OHOS 插件开发flutter_web_auth GitcodeHvigor 构建系统pubspec.yaml 插件配置开源鸿蒙跨平台社区