Flutter三方库适配OpenHarmony【secure_application】— 生产环境发布与持续维护

前言

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

代码写完、测试通过，最后一步是把插件发布出去让其他开发者用上。Flutter 插件的发布涉及 pub.dev、Gitcode、README 文档、CHANGELOG 维护等多个环节。这篇把从打包到发布到持续维护的完整流程走一遍。

一、插件打包准备

1.1 发布前检查清单

所有平台的代码编译通过
单元测试和 Widget 测试通过
在 OpenHarmony 真机上验证功能
pubspec.yaml 版本号已更新
README.md 包含 OpenHarmony 使用说明
CHANGELOG.md 记录了本次变更
LICENSE 文件存在
example/ 目录包含可运行的示例

1.2 版本号更新

yaml 复制代码

# pubspec.yaml
version: 4.2.0  # 添加 OpenHarmony 支持，次版本号 +1

json5 复制代码

// ohos/oh-package.json5
"version": "1.0.0"

1.3 dart analyze 检查

bash 复制代码

# 静态分析
dart analyze

# 格式化代码
dart format lib/ test/

# 检查发布问题
flutter pub publish --dry-run

常见的 dry-run 警告：

警告	解决方案
Missing description	添加 description 字段
Missing homepage	添加 homepage 字段
Missing LICENSE	创建 LICENSE 文件
Package too large	检查是否包含了不必要的文件

二、oh-package.json5 版本管理

2.1 版本同步策略

策略	pubspec.yaml	oh-package.json5	适用场景
完全同步	4.2.0	4.2.0	推荐
独立版本	4.2.0	1.0.0	OpenHarmony 首次发布
主版本同步	4.2.0	4.0.0	折中方案

2.2 推荐做法

json5 复制代码

// oh-package.json5
{
  "name": "secure_application",
  "version": "4.2.0",  // 与 pubspec.yaml 保持一致
  "description": "Secure app content visibility when user leave app - OpenHarmony plugin",
  "main": "index.ets",
  "author": "neckaros",
  "license": "MIT",
  "dependencies": {}
}

2.3 版本变更记录

在 oh-package.json5 旁边维护一个 CHANGELOG：

markdown 复制代码

# OpenHarmony Plugin Changelog

## 4.2.0
- 初始 OpenHarmony 适配
- 支持 setWindowPrivacyMode 截屏防护
- 支持窗口事件监听和生命周期回调
- 支持 secure/open/lock/unlock/opacity 方法

三、README 多语言文档

3.1 英文 README

markdown 复制代码

# secure_application

Secure your Flutter app content when user leaves the app.

## Platform Support

| Platform | Screenshot Protection | App Switcher | Blur Overlay |
|----------|----------------------|-------------|-------------|
| Android  | ✅ FLAG_SECURE       | ✅ Auto     | ✅ Flutter  |
| iOS      | ❌                   | ✅ Native   | ✅ Flutter  |
| OpenHarmony | ✅ PrivacyMode    | ✅ Auto     | ✅ Flutter  |
| Web      | ❌                   | N/A         | ✅ Flutter  |
| Windows  | ❌                   | N/A         | ✅ Flutter  |

## OpenHarmony Setup

Add to your app's `module.json5`:
\```json5
{
  "requestPermissions": [
    { "name": "ohos.permission.PRIVACY_WINDOW" }
  ]
}
\```

## Usage
\```dart
SecureApplication(
  onNeedUnlock: (controller) async {
    controller?.authSuccess(unlock: true);
    return null;
  },
  child: SecureGate(
    blurr: 20,
    opacity: 0.6,
    child: YourApp(),
  ),
)
\```

3.2 中文 README（OpenHarmony 专用）

markdown 复制代码

# secure_application OpenHarmony 适配说明

## 环境要求

| 要求 | 版本 |
|------|------|
| Flutter-OHOS SDK | 3.35.7-dev |
| DevEco Studio | 6.0.2 Release |
| OpenHarmony SDK | API 20 |
| 设备 ROM | 6.0.0.130 SP8 |

## 权限声明

在宿主应用的 `module.json5` 中添加：
\```json5
{
  "requestPermissions": [
    { "name": "ohos.permission.PRIVACY_WINDOW" }
  ]
}
\```

## 功能说明

- ✅ 截屏防护（setWindowPrivacyMode）
- ✅ 录屏防护
- ✅ 应用切换器内容隐藏
- ✅ 模糊遮罩（Flutter BackdropFilter）
- ✅ 认证解锁
- ✅ 前后台切换检测

3.3 文档维护原则

原则	说明
保持同步	代码变更时同步更新文档
示例优先	用代码示例而不是纯文字说明
版本标注	标明每个功能的最低版本要求
平台差异	明确标注各平台的能力差异

四、CHANGELOG 规范维护

4.1 格式规范

markdown 复制代码

# Changelog

## [4.2.0] - 2024-03-15

### Added
- OpenHarmony platform support
- `setWindowPrivacyMode` for screenshot protection on OpenHarmony
- Window event listener for app switch detection
- Application lifecycle callback for foreground/background detection

### Changed
- Updated pubspec.yaml with ohos platform declaration

### Fixed
- None

## [4.1.0] - 2024-01-10

### Added
- Windows platform support

4.2 Breaking Changes 管理

markdown 复制代码

## [5.0.0] - 2024-06-01

### BREAKING CHANGES
- `SecureApplicationController` constructor now requires `SecureApplicationState`
- Removed deprecated `setSecured` method, use `secure()` instead
- Minimum Flutter version bumped to 3.10.0

### Migration Guide
\```dart
// Before (4.x)
final controller = SecureApplicationController();

// After (5.0)
final controller = SecureApplicationController(SecureApplicationState());
\```

4.3 CHANGELOG 与 Git Tag 的对应

bash 复制代码

# 发布新版本时打 Tag
git tag v4.2.0
git push origin v4.2.0

CHANGELOG 版本	Git Tag	pub.dev 版本
[4.2.0]	v4.2.0	4.2.0
[4.1.0]	v4.1.0	4.1.0

五、发布到 pub.dev

5.1 发布命令

bash 复制代码

# 最终检查
flutter pub publish --dry-run

# 正式发布
flutter pub publish

5.2 发布注意事项

注意事项	说明
不可撤回	发布后无法删除版本
版本号递增	不能发布已存在的版本号
包大小限制	最大 100MB
需要 Google 账号	首次发布需要验证

5.3 .pubignore 配置

复制代码

# .pubignore
.idea/
.vscode/
build/
*.iml
.DS_Store
coverage/
doc/

六、发布到 Gitcode

6.1 创建仓库

在 Gitcode 上创建仓库：

bash 复制代码

# 推送到 Gitcode
git remote add gitcode https://gitcode.com/oh-flutter/secure_application.git
git push gitcode main

6.2 仓库结构

复制代码

secure_application/
├── lib/                    # Dart 源码
├── android/                # Android 原生代码
├── ios/                    # iOS 原生代码
├── ohos/                   # OpenHarmony 原生代码
├── windows/                # Windows 原生代码
├── example/                # 示例应用
├── test/                   # 测试
├── pubspec.yaml            # 包配置
├── README.md               # 英文文档
├── README.OpenHarmony_CN.md # 中文文档
├── CHANGELOG.md            # 变更日志
├── LICENSE                 # 许可证
└── .gitignore              # Git 忽略规则

6.3 Release 发布

在 Gitcode 上创建 Release
选择对应的 Git Tag
填写 Release Notes（可以从 CHANGELOG 复制）
上传编译好的 HAR 包（可选）

七、社区运营与持续维护

7.1 Issue 模板

markdown 复制代码

<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
## Bug 描述
简要描述遇到的问题。

## 复现步骤
1. 调用 `controller.secure()`
2. 按 Home 键切到后台
3. 截屏
4. 截屏结果不是黑屏

## 期望行为
截屏应该得到黑屏。

## 环境信息
- Flutter 版本：
- OpenHarmony SDK 版本：
- 设备型号：
- ROM 版本：

7.2 PR 审核流程

步骤	检查内容
1	代码风格是否一致
2	是否有测试覆盖
3	是否更新了 CHANGELOG
4	是否影响其他平台
5	是否有 Breaking Changes

7.3 版本发布节奏

类型	频率	内容
补丁版本	按需	Bug 修复
次版本	每月	新功能
主版本	每年	Breaking Changes

7.4 依赖更新

bash 复制代码

# 检查过期依赖
flutter pub outdated

# 更新依赖
flutter pub upgrade

定期检查 rxdart 和 Flutter SDK 的更新，确保兼容性。

总结

本文完成了 secure_application 的生产环境发布流程：

发布前检查：代码分析、测试通过、版本号更新
版本管理：pubspec.yaml 和 oh-package.json5 版本同步
文档维护：英文 README + 中文 OpenHarmony 文档
CHANGELOG：规范格式、Breaking Changes 标注
社区运营：Issue 模板、PR 审核、版本发布节奏

下一篇是本系列的最后一篇------总结回顾与隐私保护技术展望。

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

相关资源：