Flutter三方库适配OpenHarmony【flutter_speech】— pubspec.yaml 多平台配置

前言

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

pubspec.yaml是Flutter插件的"身份证"——它告诉Flutter框架这个插件支持哪些平台、每个平台的入口类是什么、需要哪些依赖。适配OpenHarmony后，需要在pubspec.yaml中添加ohos平台的声明，让Flutter知道"这个插件也支持OpenHarmony"。

这个配置看起来简单，但有不少细节容易出错。今天把pubspec.yaml中与多平台相关的所有配置都讲清楚。

一、plugin.platforms 配置详解

1.1 flutter_speech的完整配置

1.2 各字段含义

1.3 各平台的配置差异

1.4 ohos的package字段

ohos:
package: com.flutter.speech_recognition
pluginClass: FlutterSpeechPlugin

package对应的是oh-package.json5中的模块名，Flutter-OHOS框架通过这个名称找到插件的原生代码。

pluginClass对应的是index.ets中导出的类名：

// ohos/src/main/ets/components/plugin/index.ets
export { FlutterSpeechPlugin } from './FlutterSpeechPlugin';

1.5 pluginClass命名的注意事项

flutter_speech在OpenHarmony上用了不同的类名（FlutterSpeechPlugin而不是FlutterSpeechRecognitionPlugin），这是完全可以的——每个平台的pluginClass可以不同。

💡 为什么用不同的类名：OpenHarmony的实现是全新编写的，不是从Android翻译过来的，用一个更简洁的类名更合适。

二、ohos 平台的 package 与 pluginClass 声明

2.1 package与oh-package.json5的关系

# pubspec.yaml
ohos:
package: com.flutter.speech_recognition

// ohos/oh-package.json5
{
"name": "com.flutter.speech_recognition",
"version": "1.0.0",
// …
}

两处的名称必须完全一致。Flutter-OHOS框架在编译时会根据pubspec.yaml中的package名称去查找对应的oh-package。

2.2 pluginClass与index.ets的关系

# pubspec.yaml
ohos:
pluginClass: FlutterSpeechPlugin

// ohos/src/main/ets/components/plugin/index.ets
export { FlutterSpeechPlugin } from './FlutterSpeechPlugin';

Flutter-OHOS框架会从index.ets中导入pluginClass指定的类，并在引擎启动时自动注册。

2.3 常见配置错误

三、多平台插件的版本兼容策略

3.1 版本号管理

name: flutter_speech
description: A speech recognition plugin for Flutter
version: 0.3.0+1

3.2 添加OpenHarmony支持的版本策略

添加新平台支持属于"向后兼容的功能新增"，应该增加次版本号：

# 添加OpenHarmony支持前
version: 0.3.0

# 添加OpenHarmony支持后
version: 0.4.0

3.3 平台特定的功能差异

由于OpenHarmony只支持中文，这算是一个功能限制。应该在README和CHANGELOG中明确说明：

## 0.4.0
– Added OpenHarmony platform support
– Note: OpenHarmony currently only supports Chinese (zh_CN) speech recognition

3.4 向后兼容性

添加ohos平台不会影响现有的Android/iOS/macOS用户：

• 现有用户的pubspec.yaml不需要修改
• 现有的Dart API不变
• 只有在OpenHarmony设备上运行时才会使用ohos的原生代码

四、environment 约束：SDK 与 Flutter 版本要求

4.1 当前配置

environment:
sdk: '>=3.0.0 <4.0.0'
flutter: ^3.0.0

4.2 Flutter-OHOS SDK版本

Flutter-OHOS基于特定版本的Flutter SDK，需要确保兼容：

4.3 版本约束建议

environment:
sdk: '>=3.0.0 <4.0.0'
flutter: '>=3.0.0'

使用>=3.0.0而不是^3.0.0，给Flutter-OHOS SDK更大的兼容空间。

4.4 OpenHarmony SDK版本

OpenHarmony SDK版本在oh-package.json5中指定，不在pubspec.yaml中：

// ohos/oh-package.json5
{
"devDependencies": {
"@ohos/flutter_ohos": "file:../har/flutter_ohos.har"
}
}

五、依赖管理与发布注意事项

5.1 依赖声明

dependencies:
flutter:
sdk: flutter

dev_dependencies:
flutter_test:
sdk: flutter

flutter_speech没有第三方依赖，只依赖Flutter SDK本身。这是一个好的实践——减少依赖可以降低版本冲突的风险。

5.2 发布到pub.dev

如果要发布到pub.dev，需要注意：

5.3 发布到Gitcode/OpenHarmony生态

OpenHarmony社区有自己的包管理平台。发布时需要：

5.4 .gitignore配置

# Flutter
.dart_tool/
.packages
build/

# OpenHarmony
ohos/.preview/
ohos/build/
ohos/node_modules/
ohos/.cxx/

5.5 发布前检查清单

• pubspec.yaml中所有平台配置正确
• 版本号已更新
• CHANGELOG已更新
• README包含OpenHarmony的使用说明
• 示例代码在所有平台上可运行
• 所有测试通过
• .gitignore包含构建产物
• LICENSE文件存在

六、完整的pubspec.yaml示例

name: flutter_speech
description: A speech recognition plugin for Flutter supporting Android, iOS, macOS, and OpenHarmony.
version: 0.4.0
homepage: https://github.com/jaumard/flutter_speech_recognition

environment:
sdk: '>=3.0.0 <4.0.0'
flutter: '>=3.0.0'

dependencies:
flutter:
sdk: flutter

dev_dependencies:
flutter_test:
sdk: flutter

flutter:
plugin:
platforms:
android:
package: bz.rxla.flutter.speechrecognition
pluginClass: FlutterSpeechRecognitionPlugin
ios:
pluginClass: FlutterSpeechRecognitionPlugin
macos:
pluginClass: FlutterSpeechRecognitionPlugin
ohos:
package: com.flutter.speech_recognition
pluginClass: FlutterSpeechPlugin

每一行都有明确的作用，没有多余的配置。

总结

本文讲解了flutter_speech的pubspec.yaml多平台配置：

下一篇我们讲持续语音识别与长录音——如何突破60秒的限制实现长时间语音识别。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！

相关资源：

• Flutter Plugin pubspec.yaml规范
• pub.dev发布指南
• oh-package.json5规范
• Semantic Versioning
• flutter_speech pubspec.yaml
• 开源鸿蒙跨平台社区