最近团队在忙一件让所有 Flutter 基建同学都头大的事把组件库体系从“一套 Android/iOS 走天下”改造成“Android、iOS、鸿蒙三端统一供给”。组件本身改起来倒还好真正卡住进度的是依赖分发和版本治理。同一个组件在 Android 上能编过到了鸿蒙工程里却拉不到正确的包开发同学急着联调只能到处手工拷贝出错以后还没法追溯。于是就有了 smartpub 这个项目。smartpub 定位很直接一套面向 Flutter 组件和鸿蒙 HarmonyOS 制品的私有化包管理仓库负责组件发布、依赖解析、性能缓存和全链路审计。它解决的不只是“下载快一点”的问题而是把整个组件生态的依赖来源、版本口径和交付质量统一收口。适合正在做鸿蒙适配的 Flutter 组件库团队、移动基础架构团队以及被依赖冲突和版本漂移折腾到头疼的研发组织参考。这篇实战总结我会从为什么需要它、架构怎么搭、客户端怎么接、依赖怎么治理以及上线后踩过的坑完整过一遍。1. 立项前先想明白鸿蒙适配为什么把包管理问题推到了台前1.1 鸿蒙适配带来的依赖链变化Flutter 在鸿蒙上的落地通常走的是 OpenHarmony SDK 适配层这条路。也就是说Flutter engine 和第三方插件都要产出能在鸿蒙工程里链接的形态最常见的产物是 HAR也就是鸿蒙静态共享包以及 HSP动态共享包。这和 Android 的 AAR、iOS 的 Framework 并不是一套体系原来的 Flutter 依赖分发模型天然覆盖不到。结果就是依赖链从“一条线”变成了“一个网”组件不再只是 Dart 代码还带上了原生 so、ArkTS 接口、资源文件以及对应的构建产物。任何一个环节只要处于“半适配”状态集成时就会报找不到符号、架构不匹配、资源冲突这一类问题。依赖源作为所有这些产物的统一入口必须被重新设计。公网源的局限在项目进入规模化之后会变得很致命。它只能覆盖标准 Dart 包承载不了带厂商私有 SDK 接口的内部组件版本一旦发布后面的更新记录只有 ChangeLog没有审计信息团队大了以后谁在什么时间用了哪个版本完全没有闭环。我们出现过很典型的现场某基础包连续发布了两个小版本A 组在周一拉到 2.4.1B 组在周五拉到 2.4.2两边各自联调都没问题到了集成环境却因为行为差异吵了一周。这个锅不能全怪组件质量根子在依赖分发没有统一入口。1.2 组件库的“双轨”发布模型我们定下来的第一个原则是“内外双轨”。外部第三方包可以照常通过上游源代理缓存但内部组件必须走私有发布链路并且所有进入项目的依赖都要经过统一解析。双轨模型的长处是职责清晰上游源负责“有没有这个包”私有仓库负责“这个包能不能用”。内部组件未经审批不能推送到任何环境第三方包的获取也不能绕过缓存和校验。这样设计还有一个隐藏收益——依赖来源可审计。每次pub get都能在服务端留下记录当出现安全通告时只需要查“哪些工程引用了这个版本”就能精准定位而不是靠群聊喊话。后面做依赖治理时这个模型帮了大忙。1.3 为什么自研 smartpub 而不是直接套用通用制品仓库可能有人会问直接用现成的通用制品仓库不就行了我们评估过市面上的通用方案。它们对 Maven、Docker、npm 这类生态确实很成熟但到了 pub 生态问题就出来了pub 的版本约束解析不是简单的“按路径取文件”它依赖 metadata 中完整的依赖关系图。通用制品仓库很难感知 pubspec 里的 constraints、sdk 约束、dependency_overrides这些语义强行用会有不少边缘情况要自己兜。自建 smartpub 的另一个理由是性能可控。它只需要专注 Flutter 和鸿蒙相关制品路由、缓存、权限模型都可以按我们的使用场景定制。它不是一个大而全的平台而是一个“贴近组件库真实工作流”的轻量服务。后面所有优化都建立在这个取舍上。2. 私有化仓库架构设计smartpub 的存储、缓存与权限模型2.1 请求链路一次说清一次pub get在 smartpub 侧的处理路径是这样的客户端首先请求包版本列表接口smartpub API 网关从本地元数据库返回版本信息如果本地没有或者缓存过期网关会去上游源按协议拉取并把结果写入本地。真正下载包文件时网关会先检查对象存储命中则直接走内部带宽未命中再去上游拿文件同时做哈希校验。这个链路里有三个同步设计需要注意。第一所有需要回源的请求都带短期锁避免同一个冷门包被十个并发请求同时回源打爆上游。第二包文件一旦写入永久缓存除非手动失效否则不再轮询上游因为文件是不可变对象哈希对上就永远能用。第三版本列表接口设置短周期失效兼顾新鲜度和性能。这是架构里最容易想当然的地方很多人会把“缓存文件”和“缓存元数据”混在一起最后要么版本更新不及时要么把上游请求打得激增。2.2 元数据模型不只是存一份包数据库设计时最核心的一张表是版本表。字段需要包含包名、版本号、publish 时间、内容哈希、依赖关系 JSON、SDK 约束、发布人。依赖关系单独抽成一张表而不是字段里塞 JSON是因为要支持“谁依赖了我”这种反向查询。没有它安全通告之后你要人工在所有 pubspec 里 grep有了它一条 SQL 就能列出所有受影响工程。发布包的文件内容不落数据库放对象存储。下载时返回的地址必须带上签名有效期不能太长。文件写入前服务端会校验 sha256并和 metadata 里登记的一致才确认发布成功这能识别出上传过程中损坏的包。我们还额外存了一份“发布原始包”的冷备份防止误删或恶意覆盖后彻底丢失。2.3 缓存与回源策略缺什么补什么内部包永远优先。无论上游是否发布了同名包smartpub 只认本地仓库里经过审批的版本。第三方包则走代理缓存策略上分两层版本列表短缓存包文件长缓存。版本列表是动态的上游可能随时更新给它一个 60 秒的 TTL 比较合适代价可以忽略。包文件是不可变的只要哈希对得上缓存多久都不怕所以直接永久保存。还有一个很实用的细节回源采用“缺什么补什么”而不是整库同步。定时任务每天拉取上游版本列表增量但不会把每个版本的包文件都搬回本地。只有等到有人实际请求某个文件时才回源拉取。这样冷门包不会浪费磁盘热门包又总能命中。实测下来一套两百多个依赖的工程首次拉取后第二次pub get基本不需要落到上游。2.4 权限与安全模型最小权限是底线仓库按环境划分proxy 源代理第三方包internal-stable 和 internal-beta 分别对应稳定版和灰度版。发布的权限按包名前缀授权比如核心网络库只能由某个特定小组发布。CI 账号用短期 token不允许用开发者个人密码。拉取侧权限相对宽松但所有请求都有审计记录。这里有个经验token 的作用域不要图省事全开。我们早期为了配置简单给所有 CI 同一个全权限 token后来发现只要某个流水线脚本泄露整个仓库面临风险。改成最小权限后单个包仓库的泄露影响面被压缩到可控范围内。另外所有管理操作都建议走二次确认比如某个版本要执行删除必须由负责人和仓库管理员分别确认避免手滑。3. 动手落地Flutter 组件接入 smartpub 的完整流程3.1 客户端的源配置三分钟切到私有仓库在 Flutter 工程侧连接 smartpub 其实就是在pub get前指定源地址。最直接的方式是设置环境变量export PUB_HOSTED_URLhttps://smartpub.internal.example.com export PUB_CACHE/workspace/shared-cache建议把这种配置固化在工程根目录的.pubrc里不同环境的仓库地址写在不同 CI 变量中而不是硬编码到 pubspec。这样本地调试、测试环境、生产环境切换才不会踩坑。如果团队用统一的开发容器也可以把环境变量写进容器初始化脚本让每个成员拿到一致的环境。要注意共享PUB_CACHE时很容易出现“缓存中毒”。两个不同权限的工程共用同一个缓存目录A 工程拉到的私有包可能被 B 工程直接复用但 B 工程其实没有访问权限。我们的做法是 CI 上每个工程用自己的缓存目录或者至少用 token 区分缓存 key。本地开发则建议不共享这个目录坏了重建的成本比排查一次缓存问题低得多。3.2 pubspec 配置与鸿蒙产物联合解析在 pubspec 中引用内部组件和普通第三方包没有区别只需要保证名称和版本约束正确name: demo_app environment: sdk: ^3.0.0 dependencies: flutter: sdk: flutter core_network: ^2.1.0 core_ui: ^1.8.2真正需要额外处理的是鸿蒙原生产物的联合解析。内部组件发布时smartpub 需要额外登记一个x-ohos-modules字段用来描述该版本对应 HAR 的包名、版本和产物哈希。这样鸿蒙工程在集成时不仅可以拿到 Flutter 侧的 Dart 包还能直接从私有仓库拉取对应的 HAR 模块不会出现“Dart 代码已经更新了但原生 so 还是旧版”的错位。实现上pub 协议本身允许在 metadata 里扩展自定义字段。兼容性经过验证老版本客户端会忽略这些字段新版本客户端会用它做二次校验。这里要特别提醒HAR 产物要和 Dart 包放在同一个版本包里不要分两条发布链路。分开发很容易出现版本号对不上排查成本成倍增加。3.3 发布与校验流水线让坏包死在门外内部组件的发布流程不能手工执行必须在流水线里经过构建、扫描、人工审批三关。我们用的简化流程如下smartpub publish core_network --version 2.1.0 \ --archive dist/core_network.zip \ --har dist/core_network.har \ --release-notes fix: 修复弱网重试失效问题发布前流水线会依次执行单元测试、鸿蒙真机编译冒烟、许可证扫描、漏洞扫描。只有全部通过包才会进入 internal-beta稳定版的发布额外要求相关负责人在平台上确认。这些步骤看起来麻烦但能避免“发上去的包在鸿蒙工程里编不过”这种低级事故。发布之后还有一步容易被忽略通知。smartpub 会在新版本进入稳定仓库时向已引用该组件的工程 owner 推送一条变更摘要。这个机制看起来简单却让团队里每个人都对版本变更保持敏感没人再等到集成报错才去查谁发了什么。3.4 性能调优实测从 40 秒到 4 秒调整前一个中等规模 Flutter 工程更新依赖需要 40 秒左右其中大量时间花在上游源请求和重复回源上。smartpub 上线后我们把pub get压缩到 4 秒内。主要做了四件事第一pub 客户端保持连接复用减少 TLS 握手开销第二版本列表接口加解析缓存相同约束的请求直接返回结果第三组件依赖元数据的响应体做了压缩减少传输量第四把原先的逐包下载改成策略化预取。这个性能提升对开发者体验影响很大因为pub get是高频操作一天几十次每次省 30 秒累积下来非常可观。而且当团队规模上到几十人以后对上游源的并发压榨也会减少整个外网链路更稳定。4. 依赖治理把版本冲突和安全问题挡在门外4.1 版本策略从源头定规矩内部组件禁止使用any约束禁止只写不带上限的裸版本号。合理的约束格式是^2.1.0表示允许 2.x 系列内更新但不跨大版本。团队内部要形成共识大版本号变化代表不兼容变更需要发布公告小版本只做向后兼容的 bugfix 和功能增强。违反这个约定的发布应该被流水线拦截。我们会额外关注 SDK 约束字段。鸿蒙适配期间很多组件会面临 Flutter SDK 和鸿蒙 SDK 双约束如果不显式声明解析器很可能选择一个在高版本鸿蒙 SDK 上编不过的旧版包。这个字段的校验比版本号校验更隐蔽却往往是最容易踩的坑。4.2 依赖体检把冲突消灭在 CI 阶段定期执行dart pub deps查看依赖树重点检查重复的大版本、传递依赖是否扩散。smartpub 提供反向依赖查询以后体检可以做得更精准。比如当某个底层包有漏洞时不是靠人工盘点而是列出所有受影响组件和工程。依赖冲突的解决优先级应该遵循就近解析、最小变更的原则能用约束收紧解决就不引入 override。这里建议用表格记录一份依赖全景图组件名当前版本依赖方数量是否跨大版本重复处理建议core_network2.1.07否保持legacy_utils0.9.2 / 1.0.3 同时存在5是推动迁移 1.0.3model_api3.2.13否关注发布节奏这张表不需要做得太复杂每周跑一次有变化就自动差分发到相关群。坚持三个月依赖问题基本不会拖到集成阶段。4.3 安全与合规扫描发布和拉取双关卡在发布和拉取两端都植入扫描。发布时对源码和产物做静态扫描拉取时对上游代理的第三方包做漏洞库比对。许可证方面我们会强制拒绝 GPL 类组件进入内部仓库避免后续交付出现授权风险。所有扫描结论都记入包的审计日志方便交付前后检查。这个环节最容易被忽视的是二进制产物扫描。Dart 代码层面的漏洞扫描大家都会做但 HAR 里的 so 文件、资源文件往往不进扫描范围。我们后来补上了对 so 的符号表检查和架构白名单校验才算是真正把住了关。4.4 治理效果从人工喊话到自动拦截没有治理之前新增一个依赖就是 PR 里一句“这个库挺好的”完全靠人的自觉性。治理之后CI 会自动检查依赖树、禁止引入重复大版本发布未过扫描的包不能被任何工程拉取。整个流程变成制度化的效果对比非常明显维度治理前治理后版本来源各团队各自拉取来源混乱统一经过 smartpub来源可追溯冲突处理集成时爆发靠人协调CI 阶段自动检测提前拦截安全通告全公司群里滚动排查反向依赖查询分钟级列清单新增依赖PR 里口头说明必须过扫描和评审记录归档这套治理机制不仅解决技术问题还让团队协作从“出了问题再补救”变成“出问题前就拦下”。5. 上线后我遇到的坑现象、排查与修复5.1 同样的 pubspec 在不同机器解析出不同版本现象开发机刚 pull 完代码pub get发现依赖版本和 CI 环境不同怀疑是缓存问题。排查后发现根因是部分组件在 pubspec 中用了区间约束而两边拉包的先后顺序不同上游刚发布了新版本导致一个拉到旧版一个拉到新版。解决所有工程强制提交 pubspec.lockCI 和本地都用 lockfile 锁定解析结果发布新版本后由 smartpub 触发缓存失效而不是等 TTL 自然过期。事后复盘时我们还发现早期没有锁文件的一个重要原因是每次合并代码都会产生大量 lockfile 冲突。后来把 lockfile 的更新策略改成“由发布流水线统一更新”冲突就消失了。5.2 HAR 包在鸿蒙工程里“装上但符号找不到”现象Flutter 侧编译通过但鸿蒙侧编译报 undefined symbol。排查包虽然发布了但 HAR 内的 ArkTS 导出文件没有包含新接口架构匹配也没有问题纯粹是产物不完整。这表明发布流程缺少对鸿蒙产物的完整性校验。解决smartpub 发布流水线增加 hvigor 构建校验发布前检查oh-package.json5中声明的 export 是否完整同时对 HAR 内 so 架构做白名单检查。需要强调的是这种问题在真机上不一定暴露但一旦别人引用某个符号就会立刻编译失败因此校验必须前置。5.3 私有源和上游源混用时的优先级问题现象组件 core_network 同时存在于私有源和上游源部分机器拉到了上游旧版本行为不一致。原因是客户端配置了多个源解析顺序没有统一约束导致同一个包在不同环境落到不同仓库。解决不允许客户端自己配置多个源所有源统一由 smartpub 代理并且服务端逻辑固定为“私有命中优先私有未命中再代理上游”。这样不管客户端环境变量怎么折腾裁决逻辑都在一个地方。从运维角度看这也让故障排查简单了不少因为只查一个入口的状态就行。5.4 对象存储膨胀缓存清理要聪明一点现象磁盘告警发现缓存了大量旧版本。简单粗暴的清理会引发新问题某天有个工程回滚到旧版本结果对应文件被清了只能重新回源拉取速度慢且不稳定。解决增加版本清理策略保留每个包最近 N 个版本超过阈值的包文件移到冷存储同时定期清理过期签名。清理前要确认没有任何工程在依赖这些版本smartpub 会先跑一次反向依赖查询确认无引用后再清理。这个“先查询再清理”的操作顺序建议所有仓库管理员都刻在脑子里。最后再分享一个小实践做包管理这件事表面上是搭一个源服务器实际大部分精力都是在治“人情世故”。我最深的体会是依赖治理的收益不是上线那一刻体现的而是在三个月后某个安全通告里、在一个陌生组件突然无人维护时体现出来的。最后分享一个小实践每次发布组件时在 metadata 里强制带上 release notes不需要多长一句话就好。这个字段会让后续的版本追溯变得非常省力排查问题的时候能省下大量沟通成本强烈建议加上。