GitLab 上 KMP 二进制的发布链路与踩坑

背景 把 Kotlin Multiplatform 共享库以 XCFramework 形式发给 iOS 侧使用时,发布链路并不只是「编出来传上去」。它涉及 XCFramework 构建、二进制归档、私有 CocoaPods Specs 仓库、GitLab 包 registry,以及一连串的权限与凭据隔离问题。这里把一次完整发布踩过的坑整理成可复用的清单。 推荐发布链路 flowchart LR A[构建 XCFramework] --> B[打包 ZIP + SHA256] B --> C[生成二进制 Podspec] C --> D[上传 GitLab Generic Package] D --> E[匿名下载并校验 ZIP/SHA] E --> F[pod spec lint] F --> G[push Podspec 到私有 Specs Git] G --> H[重新 clone / readback] H --> I[干净 Podfile 执行 pod install] 名词解释 XCFramework:Apple 的跨平台 / 多架构二进制分发格式,可同时携带真机与模拟器 slice。 Podspec:CocoaPods 的依赖描述文件,声明版本、源码 / 二进制地址与校验和。 Specs 仓库:存放 Podspec 的私有 Git 仓库,相当于私有 CocoaPods 源。 Generic Package Registry:GitLab 提供的通用二进制包仓库,用来托管 ZIP 等任意产物。 Project Access Token:GitLab 的项目级访问令牌,区别于个人令牌,可限定角色与权限范围。 1. 版本必须全链路一致 以下字段必须保持一致:Git tag、VERSION_NAME、Podspec 的 version、Package Registry 路径、ZIP 文件名、checksum sidecar 文件名,以及 Specs 路径(如 UgreenHomeShared/1.7.0.4/UgreenHomeShared.podspec)。 ...

September 22, 2026