前言

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

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

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

一、plugin.platforms 配置详解

1.1 flutter_speech的完整配置

1.2 各字段含义

字段	含义	必填
platforms	支持的平台列表	✅
package	原生包名/模块名	Android和ohos必填
pluginClass	原生端插件入口类名	✅

1.3 各平台的配置差异

平台	需要package	pluginClass	原因
android	✅	FlutterSpeechRecognitionPlugin	Java包名定位类
ios	❌	FlutterSpeechRecognitionPlugin	ObjC无包名概念
macos	❌	FlutterSpeechRecognitionPlugin	同iOS
ohos	✅	FlutterSpeechPlugin	ArkTS模块名定位类

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命名的注意事项

平台	pluginClass	说明
android	FlutterSpeechRecognitionPlugin	和Java类名一致
ios	FlutterSpeechRecognitionPlugin	和ObjC类名一致
ohos	FlutterSpeechPlugin	和ArkTS export的类名一致

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 常见配置错误

错误	症状	解决
package名称不匹配	编译时找不到插件	确保pubspec.yaml和oh-package.json5一致
pluginClass名称不匹配	运行时插件未注册	确保和index.ets导出的类名一致
缺少ohos平台声明	OpenHarmony上MissingPluginException	添加ohos配置
pluginClass拼写错误	运行时报错	仔细检查大小写

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

3.1 版本号管理

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

字段	含义	示例
主版本号	不兼容的API变更	0 → 1
次版本号	向后兼容的功能新增	3
修订号	向后兼容的bug修复	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，需要确保兼容：

Flutter-OHOS版本	基于Flutter版本	Dart SDK
3.35.7-dev	Flutter 3.x	Dart 3.x

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，需要注意：

1. pub.dev目前不支持ohos平台的验证
2. 但ohos配置不会影响发布——pub.dev会忽略不认识的平台
3. 需要确保其他平台（Android/iOS）的代码正常

5.3 发布到Gitcode/OpenHarmony生态

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

1. 确保oh-package.json5配置正确
2. 提供完整的README文档
3. 包含示例代码
4. 通过社区审核

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多平台配置：

1. platforms配置：ohos需要package和pluginClass两个字段
2. 名称一致性：package与oh-package.json5一致，pluginClass与index.ets导出一致
3. 版本策略：添加新平台支持增加次版本号
4. 环境约束：兼容Flutter-OHOS SDK的版本范围
5. 发布注意：pub.dev会忽略ohos配置，不影响现有发布

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

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

---

相关资源：

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