从 pub.dev 上约 8.9 万个包出发，用一条七步的数据流水线核验鸿蒙适配来源，把 Flutter 三方库的适配现状整理成可以自动更新的清单，并区分已经适配、无需适配和需要社区认领适配三类库。

从 pub.dev 全量 89029 个包出发，通过自动化流水线核验，把”Flutter 鸿蒙适配现状”变成一份可随时更新的数据清单——这就是 flutter-ohos-adaptation-checklist[1] 做的事。这篇文章记录我是如何实现的，以及关于助力开源鸿蒙跨平台框架生态繁荣的一些思考。

一、背景：Flutter 鸿蒙化的机遇与最痛的短板

HarmonyOS / OpenHarmony 生态发展至今，跨平台框架的鸿蒙化已经走过了从“能不能跑”到“跑得好不好”的阶段。Flutter 作为最主流的跨平台框架之一，通过 CPF-Flutter 维护的 Flutter OHOS fork（如 oh-3.44.9-dev 分支）可以在鸿蒙设备上运行。对开发者来说，这意味着一个巨大的机会：一套代码，多端发布。

但横亘在“能跑”和“能用”之间的，是一个非常现实的问题——三方库生态。Flutter 的应用几乎离不开三方库：相机、地图、推送、支付、图表、动画……每一个都在你项目的 pubspec.yaml 里。而在鸿蒙平台上，这些库的适配情况是碎片化的：

• 有些库官方已经完成了鸿蒙适配（如 oh-flutter 组织下的 flutter_tts、flutter_sms 等）；
• 有些库是纯 Dart 实现，没有原生代码，其实直接就能用；
• 有些库没有适配，但同分类下已有成熟替代，换个库就行；
• 还有一些库完全没有替代，需要社区认领去适配。

问题在于：这些信息散落在 pub.dev、AtomGit、GitHub 各组织仓库里，没有一份权威、完整、可检索的清单。开发者只能靠试错——装一个库，跑不起来，再去搜有没有鸿蒙版本，效率极低；社区贡献者也看不到“哪些库最值得适配”，无从下手。

二、想法：把”适配现状”变成一份会自己更新的数据清单

我决定做一件事：把 pub.dev 上全部 Flutter 包的鸿蒙适配现状，系统性地盘点一遍，产出一份可自动更新的清单。

这不是一份手工整理的 Excel，而是一条数据流水线。我给自己定了三个要回答的问题：

1. 哪些库已经完成鸿蒙适配？（开发者可以直接用）
2. 哪些库无需适配？（纯 Dart，开箱即用）
3. 哪些库待适配？其中哪些有替代、哪些必须重点投入？（社区认领的方向）

想清楚之后，方案就变得清晰：数据源用 pub.dev（全球最大的 Dart/Flutter 包仓库，89029 个包），适配来源用鸿蒙社区现有的几个已知渠道（oh-flutter / CPF-Flutter / hxa-flutter 组织 + 适配文档 + Gitee 平台），匹配逻辑用脚本自动完成，最后生成多份清单文件。

三、实现：一条七步的数据流水线

整个生成过程由 scripts/ 下的七个脚本串联完成（01 → 02 → 03 → 04 → 05 → 06 → 审计），每一步都可独立运行、断点续跑：

1. 拉取 pub.dev 全量包数据

数据源是 pub.dev 的 /api/packages 接口，共 89029 个包。每个包带有包名、描述、平台信息（android / ios / ohos）、是否包含原生代码（plugin 标记）以及依赖关系。

脚本支持分页断点续跑（已抓取的页自动跳过），默认使用中国镜像 pub.flutter-io.cn 规避网络问题，也支持 –proxy 显式指定代理。输出为 JSONL 格式的 data/cache/pub-libs.jsonl（中间产物，已被 .gitignore 忽略），保证清单可复现、可审计。

2. 核验适配来源，打上”已适配”标记

我汇总了鸿蒙社区目前最主要的 6 个适配来源：

把 89029 个包逐一与这些来源做匹配。匹配的关键是键的归一化：同一个库在不同来源里写法可能不同（fluttertoast 在适配仓库里可能叫 flutter_fluttertoast，flutter_tts 也可能带 _ohos 后缀）。我设计了一套归一化规则（小写、下划线/连字符互转、去前缀），保证“同一个库”在不同写法下都能命中同一个适配记录。

这里有一个值得分享的工程细节：早期用 Python set 做匹配时，发现 set 的迭代顺序受哈希随机化影响，导致同一个输入在不同进程里生成的清单归属不稳定（同一个库有时算已适配、有时算待适配）。后来改为固定优先级的 key 列表匹配，彻底消除了随机性——这是“数据流水线”类工具最容易踩、也最容易被忽视的坑：结果必须可复现。你永远不会希望同一份数据在 CI 里和本地生成出两份不同的清单。

3. 计算待适配候选，按 2 年更新规则剔除

对待适配的 Flutter 插件（含平台原生代码），脚本会拉取每个包的最新发布时间，只保留近 2 年内有更新的库进入待适配清单——2 年未更新的库维护停滞，适配价值低，不再列示。这个规则可以通过 –cutoff 调整，也可以用 –no-2yr-filter 完全关闭。

4. 拆分纯 Dart 库，做依赖链核验

不含原生代码的纯 Dart 包原则上不需要适配，但这里有一个隐藏陷阱：一个纯 Dart 库可能依赖了某个未适配的原生插件，那它照样跑不起来。比如某个表单库依赖了未适配的相机插件。

所以这一步会对纯 Dart 候选逐个检查依赖链：只有”自身无原生代码 且 依赖链不含未适配原生插件“的库才真正归入”无需适配“；依赖了未适配原生插件的，会被单独列出为”例外”，等其依赖的插件适配完成后即可直接可用。

5. 生成多份清单文件

最后把结果渲染为多份 Markdown 文件，作为仓库的“产品”：

一次盘点，全貌尽收眼底：909 个已适配 + 69032 个纯 Dart 可直接用 + 19069 个待适配（其中 3495 个纯 Dart 例外依赖待适配插件）。对开发者而言，“某个库在鸿蒙上能不能用”不再靠猜；对贡献者而言，“该适配谁”有了明确答案。

6. 搜索补漏，扩大覆盖

部分库的适配仓库可能不在上述组织的固定列表中（比如个人开发者或小组织完成的适配）。为此我增加了搜索补漏机制：对 pub.dev 候选列表中的高分库，通过 AtomGit 搜索 API 逐一检索仓库名，命中的结果并入已适配清单。这一机制累计为清单补充了 244 个搜索命中的适配仓库，显著提升了覆盖度。

7. 生成适配优先级参考

基于 CPF-Flutter/skills[8] 的适配判断规则，对候选库评估是否需要适配，并给出 P0-P3 优先级（P0 最优先），生成 adaptation-priority.md[9] 供开发者优先认领共建。

四、工程化：可复现、可自检、可持续

一个清单类工具，最怕的就是“生成一次就再也跑不起来”。所以我在工程上有三个坚持：

1. 数据快照：data/sources/ 目录固化各适配来源的抓取快照（组织仓库列表、适配文档解析结果、Gitee 清单），离线可复现，在线可刷新；data/meta.json 记录各来源数量与抓取时间，数量对不上立即发现；
2. 确定性：固定优先级 key 匹配 + 名称归一化，同一输入必然得到同一输出；
3. 自动审计：scripts/audit.py[10] 对清单文件做多项完整性自检——统计守恒（已适配 + 适配中 + 纯 Dart + 待适配 + 剔除 = 全集）、集合互斥（同一库不会同时出现在已适配和待适配）、无重复包名、Markdown 链接括号平衡、统计段与行数一致性。任何一处数字对不上，审计直接报错。

这保证了清单不是一份“死文档”，而是一个可持续演化的数据产品：适配来源新增一个库，重新生成，清单自动更新；误判被发现，改逻辑，审计兜底。

五、社区协作：把清单交给官方确认

盘点做完只是第一步。这份清单的正确性需要鸿蒙 Flutter 社区、尤其是适配工作一线的组织来把关。我做了几件事：

1. 同步 oh-flutter/third-party-libraries：把盘点结果反向同步到 oh-flutter/third-party-libraries[11]（oh-flutter 组织已适配三方库列表，自动同步更新），让社区有一个统一的已适配库入口；
2. 多来源交叉验证：适配状态同时参考 oh-flutter / CPF-Flutter / hxa-flutter 三个组织 + 官方适配文档 + Gitee 平台 + 搜索补漏，任一来源命中即视为已适配，最大限度避免漏判；
3. 开放协作入口：欢迎官方与社区在本仓库提交 Issue / PR——补充适配来源、修正数据误判、认领待适配库、分享适配经验。

清单的价值不在于“我列出来了”，而在于它成为社区协作的公共底座：官方确认结论 → 修正清单 → 适配成果回流 → 清单再更新，形成正向循环。

六、关于助力开源鸿蒙跨平台框架生态繁荣的一些思考

做完这件事，我最大的体会是：一个生态的繁荣，往往不取决于某个“杀手级框架”，而取决于那些看不见的基础设施——文档、工具链、数据，以及清晰的协作机制。 具体到鸿蒙跨平台生态，有几点思考想分享：

1. 数据透明化，是生态繁荣的第一块基石

开发者做技术选型时，最怕的不是“没有库”，而是“不知道哪个库能用”。三方库的鸿蒙适配状态，本质上是一份数据——它理应被系统性地采集、整理、公开，而不是靠每个人在群里问“xx 库有人适配过吗”。

当“能不能用”变成一张可检索的表格，开发者的迁移成本就大幅降低：纯 Dart 库直接用，已适配库放心装，有替代的换一个，没替代的知道要等。生态的繁荣，从消灭“信息差”开始。

2. 避免重复造轮子，把力量集中在刀刃上

盘点结果里有一个非常有意思的发现：19069 个待适配库中，相当一部分其实同分类下已有成熟鸿蒙化替代，或者本身只是依赖了未适配插件的纯 Dart 库（3495 个例外）。如果每个团队都闷头适配自己遇到的库，很可能出现“十个团队适配了十个类似的图表库，而最核心的地图库无人问津”的局面。**一份带分类、带优先级的清单，就是最好的“力量调度器”**——它告诉社区：这里已有替代，别重复造轮子；那里是空白，欢迎来补。

3. 清单即任务池：降低贡献门槛

开源贡献最大的门槛往往不是技术难度，而是”不知道从哪里下手“。一份按分类、按优先级（P0-P3）排好序的待适配清单，天然就是一个任务池：

• 新贡献者进来，选一个优先级高、分类清晰的库认领；
• 适配思路可以参考同分类已适配库的经验（清单里直接给了仓库链接）；
• 完成适配后把成果回流到适配来源，清单重新生成后自动更新，贡献被”看见”。

把“该做什么”摆到明面上，贡献就从偶然变成可持续。

4. 自动化与可复现，让生态数据”活”起来

手工维护的清单注定会过时。我在这件事上投入了大量精力做工程化：数据快照、固定优先级匹配保证确定性、审计脚本兜底完整性。因为我相信，生态基础设施必须能自我演化——适配来源更新了，清单要能跟着更新；数据错了，要能快速发现并修正。

5. 与官方社区协同，形成反馈闭环

我把盘点结果同步到了 oh-flutter/third-party-libraries，并邀请官方与社区在清单仓库提交 Issue / PR。这一步的价值在于：民间盘点与官方实践互相校验。官方的确认结论让清单更权威，清单又反向帮助官方了解社区需求分布。这个闭环一旦转起来，生态数据就会越来越准。

6. 展望：下一步还能做什么

这份清单只是起点。沿着这个方向，还有不少值得做的事：

• AI 辅助适配评估：结合每个库的代码结构、依赖关系，自动评估鸿蒙化适配难度与工作量，给每个库打上”难度星级”；
• 适配进度追踪：把清单做成可交互的看板，记录每个库的适配状态（认领中 / 适配中 / 已提 PR / 已发布），让社区协作可视化；
• CI 自动化：定时重新生成清单 + 跑审计，数据变更自动提交，让清单永远是最新的；
• 质量分级：区分”官方适配 / 组织适配 / 社区适配 / 实验性适配”，让开发者对每个库的成熟度心里有数。

七、相关组织与 AtomGit 共建

开源鸿蒙跨平台框架 Flutter 生态的繁荣，离不开一个个组织与项目的持续投入。这里把与本文相关的组织和项目集中列出，供大家参考与关注：

欢迎在 AtomGit 平台上共建 🤝：无论你来自哪个组织，都可以通过 AtomGit 参与这份生态基础设施的建设——

• 在 flutter-ohos-adaptation-checklist[19] 提交 Issue / PR：补充适配来源、修正清单数据、认领待适配库；
• 把适配成果回流到 oh-flutter/third-party-libraries[20] 或 CPF-Flutter/docs[21] 等适配来源，清单重新生成后自动更新；
• 在你的组织仓库中直接复用 scripts/ 下的流水线脚本与 audit.py，一起把鸿蒙跨平台生态的数据底座越做越厚。

结语

Flutter 的鸿蒙化，是开源鸿蒙生态里一块潜力巨大的拼图。而拼图的每一块，最终要靠社区一块一块拼起来。这份清单，是我能提供的、让拼图过程更快一点点的基础设施——它不直接写一行鸿蒙代码，但它让每一行鸿蒙代码都能被更快、更准地写出来。

如果你也在做鸿蒙跨平台相关的工作，欢迎到 flutter-ohos-adaptation-checklist[22] 提交 Issue / PR：修正一个误判、补充一个适配来源、认领一个库，或者只是告诉我你的使用体验。生态繁荣，始于每一个“我觉得可以更好”的行动。

参考资料

[1]flutter-ohos-adaptation-checklist: https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist

[2]adapted-libraries.md: adapted-libraries.md

[3]gitee-adapted-libraries.md: gitee-adapted-libraries.md

[4]in-progress-libraries.md: in-progress-libraries.md

[5]to-adapt-libraries.md: to-adapt-libraries.md

[6]to-adapt-last-year.md: to-adapt-last-year.md

[7]adaptation-priority.md: adaptation-priority.md

[8]CPF-Flutter/skills: https://atomgit.com/CPF-Flutter/skills

[9]adaptation-priority.md: adaptation-priority.md

[10]scripts/audit.py: scripts/audit.py

[11]oh-flutter/third-party-libraries: https://atomgit.com/oh-flutter/third-party-libraries

[12]atomgit.com/oh-flutter: https://atomgit.com/oh-flutter

[13]atomgit.com/oh-flutter/third-party-libraries: https://atomgit.com/oh-flutter/third-party-libraries

[14]atomgit.com/CPF-Flutter: https://atomgit.com/CPF-Flutter

[15]atomgit.com/CPF-Flutter/docs: https://atomgit.com/CPF-Flutter/docs

[16]atomgit.com/CPF-Flutter/skills: https://atomgit.com/CPF-Flutter/skills

[17]atomgit.com/hxa-flutter: https://atomgit.com/hxa-flutter

[18]atomgit.com/CPF-Flutter/flutter_flutter: https://atomgit.com/CPF-Flutter/flutter_flutter

[19]flutter-ohos-adaptation-checklist: https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist

[20]oh-flutter/third-party-libraries: https://atomgit.com/oh-flutter/third-party-libraries

[21]CPF-Flutter/docs: https://atomgit.com/CPF-Flutter/docs

[22]flutter-ohos-adaptation-checklist: https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist