徐翊人做Flutter-OH（OpenHarmony）侧的三方库开发时，我踩过一次印象特别深的坑：插件核心逻辑都跑通了，文档、Demo、单元测试一应俱全，提审到中心仓的时候却被驳回，理由是“兼容性信息不完整”。当时我第一反应是审核员看错了，结果人家贴出来的截图清清楚楚——oh-package.json5里的API版本范围和Flutter版本约束对不上，甚至还有一个字段的枚举值写成了旧版格式。
后来我才意识到，兼容性信息这事，看起来就是填几个版本号，实际上它是一组“可被机器验证的元数据声明”。代码层面兼容不兼容，编译器会告诉你；但仓库层面兼容不兼容，全靠你填的信息。填错了，轻则用户依赖解析失败，重则会在特定SDK版本的设备上运行闪退。这篇文章就把我整理出的完整方法写出来：兼容性信息到底包含哪些字段、各版本数据从哪查、怎么填才能既准确又能过审。
1. 为什么兼容性信息总是填错：先把三方库、OH平台与Flutter引擎的关系对齐
1.1 三者的真实关系：一个三角匹配问题
很多人在填Flutter-OH三方库的兼容性信息时，脑子里的模型是“一条线”——Flutter代码跑在OpenHarmony设备上，完事。这个模型在写业务代码时够用，但在填兼容性信息时完全不够用。
实际的关系是一个三角结构：
- Flutter侧：你用Dart写的库逻辑，依赖Flutter SDK的版本特性。比如用了某个新API，就需要最低的Flutter版本。
- OH侧：OpenHarmony系统的能力，通过ArkTS接口和系统组件暴露给上层，三方库如果调用了系统能力（蓝牙、相机、传感器等），就必须声明依赖的OH API Level范围。
- Flutter-OH引擎适配层：Flutter框架要在OpenHarmony上跑，依赖flutter_flutter和flutter_engine这两个适配分支的特定版本，这部分属于OpenHarmony社区维护的发行版。
三方库的兼容性，本质是这三个顶点之间的匹配关系。Flutter版本决定引擎可用性，OH API Level决定平台能力可用性，而引擎本身能够运行的OH系统版本，又受限于适配分支的发布节奏。
1.2 兼容性信息不只是版本号
我见过不少开发者，把兼容性信息理解成“填一个版本号范围”，比如在README里写一句"支持OpenHarmony 3.1及以上"。这种写法对人工阅读还行，但对仓库系统和包管理工具来说，信息量不够，而且无法校验。
一份能被准确识别的兼容性信息，至少包含四个维度：
| 信息维度 | 说明 | 不填或填错的后果 |
|---|---|---|
| OH API Level范围 | 库测试过的OpenHarmony系统API版本区间 | 高版本系统可能表现异常，低版本系统直接安装失败 |
| Flutter SDK版本约束 | 库依赖的Flutter/Dart SDK最低版本 | 版本解析时提示约束冲突，或者编译时API缺失 |
| 引擎适配版本 | 基于哪个Flutter-OH发行版验证通过 | 用户使用不匹配的引擎时出现运行时崩溃 |
| 依赖项版本链 | 库本身依赖的其他OH三方库版本范围 | 依赖冲突、重复符号、资源覆盖等诡异问题 |
我排查过的多数被驳回案例，都不是某个字段没填，而是这几个维度之间互相矛盾。比如声明支持API 11，但依赖的一个底层库只支持到API 10，仓库在解析时就会发现这个库在API 11环境下根本无法工作。
1.3 兼容性信息填错的真实代价
有人说，我填得不严谨，但我的库确实能跑啊。这话在本地跑通时是对的，但发布到公共仓库后，问题会被放大成三类：
第一类是安装期错误。用户用ohpm安装依赖时，工具会根据兼容性元数据判断是否满足依赖约束。元数据声明过高，用户在低版本设备上安装直接报错；声明过低，高版本系统又可能不会启用新特性路径。
第二类是运行期崩溃。最常见的是ArkTS API Level没对齐。开发者本机用的是较新的SDK，编译器允许调用某个API，但用户设备上的系统版本没有这个API，运行到该路径时直接崩。这种问题比编译错误难查得多，因为错误信息往往只出现在特定设备上。
第三类是审核驳回。中心仓对三方库的元数据严谨性有要求，兼容性声明不规范会被退回修改，消耗的完全是额外的沟通成本和时间成本。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 兼容性信息到底包含哪些字段：逐项拆解
2.1 清单文件中的标准字段：oh-package.json5
OH侧三方库的元数据核心是oh-package.json5，类似Flutter侧pubspec.yaml的角色。兼容性相关的核心配置包括依赖的SDK版本范围、API版本范围和其他包依赖。
先来看一个贴合