Flutter三方库适配OpenHarmony【flutter_speech】— 生产环境部署与发布

阿林来了2026-02-23 12:07

前言

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

代码写完了、测试通过了，接下来就是发布。发布不只是把代码推到仓库那么简单------版本管理、文档编写、包配置、社区规范，每一项都影响着插件的可用性和可维护性。

今天我们来讲flutter_speech从开发完成到正式发布的完整流程。

一、插件打包与发布到 Gitcode

1.1 发布平台选择

1.2 发布前的代码检查

bash 复制代码 
# 1. 代码格式化
dart format lib/
dart format example/lib/

# 2. 静态分析
dart analyze

# 3. 运行测试
flutter test

# 4. 检查pubspec.yaml
flutter pub publish --dry-run

1.3 发布到pub.dev

bash 复制代码 
# 登录pub.dev
dart pub login

# 预检查
dart pub publish --dry-run

# 正式发布
dart pub publish

📌 注意：pub.dev会忽略不认识的平台（ohos），所以ohos配置不会导致发布失败。但pub.dev的自动化测试只会验证Android/iOS/Web等官方平台。

1.4 发布到Gitcode/Gitee

对于OpenHarmony社区，推荐将代码托管到Gitee的openharmony-sig组织下：

bash 复制代码 
# 添加Gitee远程仓库
git remote add gitee https://gitee.com/openharmony-sig/flutter_speech_recognition.git

# 推送代码
git push gitee main

# 推送标签
git tag v0.4.0
git push gitee v0.4.0

1.5 Release发布

在代码托管平台创建Release：

  1. 选择版本标签（如v0.4.0）
  2. 填写Release标题和说明
  3. 附上CHANGELOG中对应版本的内容
  4. 标记为Latest Release

二、oh-package.json5 版本管理规范

2.1 当前配置

json5 复制代码 
{
  "name": "com.flutter.speech_recognition",
  "version": "1.0.0",
  "description": "Flutter speech recognition plugin for OpenHarmony",
  "main": "src/main/ets/components/plugin/index.ets",
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "@ohos/flutter_ohos": "file:../har/flutter_ohos.har"
  }
}

2.2 版本号与pubspec.yaml的关系

文件 版本号 说明
pubspec.yaml 0.4.0 Flutter插件版本（面向Dart开发者）
oh-package.json5 1.0.0 OpenHarmony模块版本（面向原生开发者）

两个版本号可以不同，但建议保持同步或有明确的对应关系：

复制代码 
pubspec.yaml: 0.4.0  →  oh-package.json5: 0.4.0
pubspec.yaml: 0.4.1  →  oh-package.json5: 0.4.1

2.3 版本号规范

遵循语义化版本（Semantic Versioning）：

复制代码 
MAJOR.MINOR.PATCH

MAJOR: 不兼容的API变更
MINOR: 向后兼容的功能新增
PATCH: 向后兼容的bug修复
变更类型 版本变化 示例
修复bug PATCH+1 0.4.0 → 0.4.1
新增功能（兼容） MINOR+1 0.4.1 → 0.5.0
破坏性变更 MAJOR+1 0.5.0 → 1.0.0
添加OpenHarmony支持 MINOR+1 0.3.0 → 0.4.0

2.4 依赖版本管理

json5 复制代码 
{
  "devDependencies": {
    "@ohos/flutter_ohos": "file:../har/flutter_ohos.har"
  }
}

当前使用本地文件引用。发布时可能需要改为远程引用：

json5 复制代码 
{
  "devDependencies": {
    "@ohos/flutter_ohos": "^3.35.7"
  }
}

三、README 文档编写规范与多语言支持

3.1 README结构

一个好的README应该包含以下部分：

markdown 复制代码 
# flutter_speech

Flutter speech recognition plugin with OpenHarmony support.

## Features
- Speech-to-text recognition
- Real-time partial results
- Multiple platform support (Android, iOS, macOS, OpenHarmony)

## Platform Support
| Platform | Support | Language |
|----------|---------|----------|
| Android | ✅ | 100+ languages |
| iOS | ✅ | 60+ languages |
| macOS | ✅ | 60+ languages |
| OpenHarmony | ✅ | Chinese (zh_CN) |

## Installation
## Usage
## API Reference
## Platform-specific Setup
## Troubleshooting
## Contributing
## License

3.2 OpenHarmony特有的说明

README中需要特别说明OpenHarmony的限制和配置：

markdown 复制代码 
### OpenHarmony Setup

1. Add microphone permission to your app's `module.json5`:
   ```json5
   "requestPermissions": [{
     "name": "ohos.permission.MICROPHONE",
     "reason": "$string:microphone_reason",
     "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
   }]

  1. Language support: Only Chinese (zh_CN) is currently supported.

  2. Minimum SDK: OpenHarmony API 20

    3.3 多语言README

    对于面向中国开发者的OpenHarmony插件，建议提供中英文README：

README.md # 英文（默认）

README_zh.md # 中文

复制代码 
### 3.4 徽章（Badges）

```markdown
[![pub package](https://img.shields.io/pub/v/flutter_speech.svg)](https://pub.dev/packages/flutter_speech)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Platform](https://img.shields.io/badge/platform-android%20|%20ios%20|%20macos%20|%20ohos-blue)

四、CHANGELOG 维护与版本迭代策略

4.1 CHANGELOG格式

遵循Keep a Changelog规范：

markdown 复制代码 
# Changelog

## [0.4.0] - 2025-02-14
### Added
- OpenHarmony platform support
- Core Speech Kit integration for Chinese speech recognition
- Microphone permission handling via abilityAccessCtrl
- Platform detection with Platform.isOhos

### Changed
- Updated example app with OpenHarmony language restriction

### Notes
- OpenHarmony currently only supports Chinese (zh_CN)
- Requires OpenHarmony API 20 or higher
- Requires Flutter-OHOS SDK 3.35.7 or higher

## [0.3.0] - 2024-xx-xx
### Added
- macOS platform support
- ...

4.2 变更分类

分类 含义 示例
Added 新增功能 OpenHarmony支持
Changed 功能变更 修改默认参数
Deprecated 即将移除 旧API标记废弃
Removed 已移除 删除旧API
Fixed Bug修复 修复内存泄漏
Security 安全修复 修复权限漏洞

4.3 版本迭代节奏

阶段 版本范围 迭代频率 重点
初始开发 0.1.0-0.9.0 每周 功能完善
Beta测试 0.9.0-1.0.0-rc 每两周 Bug修复
正式发布 1.0.0+ 每月 稳定性
维护期 1.x.x 按需 安全修复

五、社区贡献指南与 Issue 管理

5.1 CONTRIBUTING.md

markdown 复制代码 
# Contributing to flutter_speech

## Getting Started
1. Fork the repository
2. Clone your fork
3. Create a feature branch
4. Make your changes
5. Run tests: `flutter test`
6. Submit a pull request

## Development Setup
- Flutter-OHOS SDK 3.35.7+
- DevEco Studio 6.0.2+
- OpenHarmony device with API 20+

## Code Style
- Dart: Follow effective_dart guidelines
- ArkTS: Follow OpenHarmony coding standards
- All code must pass `dart analyze` with no issues

## Pull Request Guidelines
- One feature/fix per PR
- Include tests for new features
- Update CHANGELOG.md
- Update README if API changes

## Reporting Issues
- Use the issue template
- Include device info and SDK versions
- Include reproduction steps
- Include log output (hdc hilog)

5.2 Issue模板

markdown 复制代码 
<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: Bug Report
about: Report a bug in flutter_speech
---

## Environment
- Flutter version:
- Flutter-OHOS SDK version:
- OpenHarmony API version:
- Device model:
- DevEco Studio version:

## Description
<!-- What happened? -->

## Steps to Reproduce
1.
2.
3.

## Expected Behavior
<!-- What should have happened? -->

## Actual Behavior
<!-- What actually happened? -->

## Logs
<!-- Paste relevant logs from `hdc hilog | grep FlutterSpeechPlugin` -->

5.3 Issue标签管理

标签 颜色 含义
bug 红色 确认的Bug
enhancement 蓝色 功能请求
ohos 绿色 OpenHarmony相关
android 橙色 Android相关
ios 紫色 iOS相关
documentation 灰色 文档相关
good first issue 黄色 适合新手

5.4 PR审核流程

复制代码 
贡献者提交PR
    │
    ├── 自动化检查（CI）
    │   ├── dart analyze
    │   ├── flutter test
    │   └── 代码格式检查
    │
    ├── 代码审核（维护者）
    │   ├── 代码质量
    │   ├── 测试覆盖
    │   └── 文档更新
    │
    └── 合并
        ├── Squash merge（推荐）
        └── 更新CHANGELOG

六、发布检查清单

6.1 发布前

  • 所有测试通过
  • 代码已格式化（dart format）
  • 静态分析无警告（dart analyze）
  • pubspec.yaml版本号已更新
  • oh-package.json5版本号已更新
  • CHANGELOG.md已更新
  • README.md已更新（如有API变更）
  • 示例App在所有平台可运行
  • git tag已创建

6.2 发布中

  • pub.dev发布成功（dart pub publish）
  • Gitee/GitHub Release已创建
  • Release notes已填写

6.3 发布后

  • 在新项目中验证安装
  • 检查pub.dev页面显示正常
  • 通知社区（论坛、群组）
  • 关闭已修复的Issues

总结

本文讲解了flutter_speech的生产环境部署与发布流程：

  1. 发布平台：pub.dev + Gitee/GitHub双平台发布
  2. 版本管理：pubspec.yaml和oh-package.json5版本同步
  3. 文档规范：README结构化、CHANGELOG规范化、多语言支持
  4. 社区建设：贡献指南、Issue模板、PR审核流程
  5. 发布检查：完整的发布前/中/后检查清单

下一篇是本系列的最后一篇------总结与未来展望，我们将回顾整个适配过程并展望OpenHarmony语音识别的未来。

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

相关资源：

相关推荐
lili-felicity3 小时前
进阶实战 Flutter for OpenHarmony：Hero 动画转场系统 - 页面过渡动画实现
flutter
2601_949593653 小时前
进阶实战 Flutter for OpenHarmony：ValueNotifier 组件实战 - 轻量级状态管理系统
flutter
忙碌5443 小时前
2026年Flutter 3.16全栈实战：从UI到后端的一体化开发革命
flutter·ui
九狼JIULANG3 小时前
Flutter Riverpod + MVI 状态管理实现的提示词优化器
flutter
lili-felicity4 小时前
进阶实战 Flutter for OpenHarmony：NestedScrollView 嵌套滚动系统 - 复杂滚动交互实现
flutter
lili-felicity4 小时前
进阶实战 Flutter for OpenHarmony：PageView 无限轮播系统 - 轮播交互优化实现
flutter·交互
lili-felicity4 小时前
进阶实战 Flutter for OpenHarmony：flutter_slidable 第三方库实战 - 列表滑动
flutter
啥都想学点5 小时前
第1天：搭建 flutter 和 Android 环境
android·flutter
蓝帆傲亦5 小时前
Vue.js 大数据处理全景解析：从加载策略到渲染优化的完全手册
前端·vue.js·flutter
热门推荐
01GitHub 镜像站点02AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot03Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services04HTML 早已不是标签了，它现在是系统级接口：这 9 个 API 直接干翻常用 JS 库05全面体验 Grok API 中转站（2025 · Grok 4 系列最新版）06如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解07【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆08MIUI显示/隐藏5G开关的方法，信号弱时开启手机Wifi通话方法09openClaw安装飞书插件｜核心踩坑：spawn EINVAL 错误终极解决指南10配置 OpenClaw 使用 Ollama 本地模型