适用范围
- 应用:
home/ios/ugreenhome - 发布脚本:
home/cicd/ci - 组件:
home/ios/components/*
时间跨度:从开启 BUILD_LIBRARY_FOR_DISTRIBUTION(BLFD)开始,到 18 个 *-bin 组件重发、真机验证、cicd 收口 MR 为止。
0. 什么是 BLFD,为什么要开
BLFD = BUILD_LIBRARY_FOR_DISTRIBUTION = YES,是 Swift 的 Library Evolution / Module Stability 开关。开启后,编译器在生成二进制的同时输出一份 .swiftinterface 文件,完整描述模块对外暴露的 API。Importer 编译时优先读取 .swiftinterface,从而让一个预编译的 Swift 二进制框架可以被不同 Swift / Xcode 版本的 consumer 导入,避免小版本差异导致 ABI 破坏。
UG 的 *-bin 组件是通过 CocoaPods 分发的预编译二进制 framework,开发机、Runner CI、本地环境用的 Xcode / Swift 版本不可能完全一致。不开 BLFD 时,Swift 编译器小版本差异就可能让 consumer 在链接 / 运行时出现 Symbol not found 或 dyld: cannot load。开启后,一次发布即可跨多个 Xcode 版本使用,不用为每个 Xcode / Swift 版本各打一份二进制。
1. 基本策略(先记结论)
*-bin二进制只能由远端 GitLab tag 流水线触发打包,禁止本地pod repo push/ 本地打 zip;- 应用侧依赖切换必须走 git worktree,不要直接推
feature/1.8.0; - Nexus 是 raw 仓库(zip +
.sha256侧车文件);Specs 仓库不变量:同版本 zip 覆盖禁止(cicd MR !35 加固); - 远端 tag 流水线用
UG_COMPONENT_UPSTREAM变量覆盖,让 RxRelay / RxCocoa 等从 RxSwift 仓库的 tag 发布。
2. BLFD 相关坑
坑1:module 名 == 顶层类名,swiftinterface 无法被导入(JXSegmentedView)
module JXSegmentedView 里又声明 class JXSegmentedView,生成的 .swiftinterface 出现自限定引用,依赖方导入时 module / type 歧义,编译失败(不只是告警)。影响:所有 import 它的 *-bin 消费者全部坏掉。
处理:该组件不发布 *-bin,应用侧回退源码 pod JXSegmentedView 1.4.1(UH 系 bin 不引用它,无 resilient 符号风险)。manifest 里标记 skip: true。
坑2:BLFD 的 swiftinterface 必须可独立导入才安全
之前只在消费者侧红线才发现坏二进制。收口:在 lib.sh 加 verify_swiftinterface_module_collision,在 stage(xcframework 构建后)确定性拦截——顶层 class/struct/enum/protocol/typealias 与 module 同名,或存在 Module.Module 自限定引用。这样坏二进制在发布期就被挡下,不会流到 Specs。
坑3:组件 podspec 前缀不一致(FCUUID)
原 podspec 用 spec. 前缀而非 s.,插入的 BLFD 代码块写死了 s.,导致 lint / 生成失败。处理:按实际前缀修正后重新打 tag。
3. 发布流水线 / 脚本坑
坑4(根因):同版本 sha256 不一致
BLFD 批量重传了 zip,但 push-spec.sh --resume 跳过了 spec 更新,导致 Specs 指向旧 / 缺失的 zip,pod install 时 sha256 对不上。根因修复:组件版本号 bump(如 5.7.1 -> 5.7.1.1),并禁止同版本覆盖(MR !35)。
坑5:push-spec.sh 两个写入路径都被守卫
复查结论:push-spec.sh 是唯一写 Specs 的路径,已被「已存在即拒绝」预检 + pod repo push --no-overwrite 双重保护,同版本覆盖事故不可能再发生(已加注释固化不变量)。
坑6:glab api 包装只传了 $1
api() 把写操作(POST)静默变成 GET,导致改操作看似成功实际没做。修复:改为 GLAB api "$@"。
坑7:set -e 下 [ cond ] && echo 在函数尾部返回 1
函数最后一句是 [ ... ] && echo,条件为假时整条返回 1,在 set -e 下直接退出脚本。修复:改成 if [ cond ]; then echo; fi。
坑8:UG patch tag 在 GitHub 上游不存在
Moya / RxRelay / RxCocoa 的 UG patch 版本(5.12.2.1 等)GitHub 上游没有,lint 失败。处理:把 spec 的 :git 指向 UG 镜像而非 GitHub。
坑9:并发 specs clone 竞争
12 条流水线同时 clone 同一个 Specs 仓库,偶发竞争失败。处理:分批重试。
坑10:应用侧流水线失败,因 revert commit 只留在本地没推
JXSegmentedView 回退 commit 忘了 push,导致远端流水线 5343 红;补推后 5344 绿。教训:本地验证通过 != 远端有这个 commit,发 MR 前确认已 push。
坑11:glab api 间歇性空响应
rc=0 但 stdout 为空(快速连续调用时)。批量 python 脚本据此判断会误判。处理:用单次 shell 命令 + grep 复核,别轻信批量循环结果。
坑12:/dev/stdin 管道被 heredoc 消费函数覆盖
把内容通过 stdin 喂给一个内部用 heredoc 的函数,heredoc 会覆盖 stdin。处理:改用临时文件传参。
4. Git / 工作流坑
坑13:同一分支不能在两个 worktree 同时检出
feature/1.8.0 已在主 worktree 检出,想在 republish worktree 再 checkout 会报 already used by worktree。处理:该分支只能在主 worktree 更新;republish worktree 用独立分支。
坑14:含子模块的 worktree 不能用 git worktree remove
报 working trees containing submodules cannot be moved or removed。处理:rm -rf 工作目录,然后 git worktree prune。
坑15:删掉会话工作目录会让后续所有 Bash 命令失效
会话的工作目录就是被删的 worktree 路径;rm -rf 之后,Bash 工具每次都先 chdir 到该路径失败,所有命令返回空。处理:删之前先确认它不是会话 cwd;若已删,重建该目录即可恢复。
坑16:MR 合并后远端分支被 GitLab 自动删除
git push --delete 报 remote ref does not exist——分支其实已随 MR 合并被自动删。处理:本地残留的 remote-tracking ref 用 git branch -dr origin/branch 清掉。
坑17:fetch / push 到内网 GitLab 间歇性 SSL / 连接重置
SSL_ERROR_SYSCALL / Connection reset by peer,多为瞬时;重试即可(ls-remote 正常说明网络 / 鉴权是好的)。
5. 工具 / REPL 坑
坑18:git push 的进度输出让 REPL 解析崩溃
push 的 progress 行里带冒号,REPL JSON 解析报 Unexpected token ':'。处理:加 --no-progress,或把输出重定向到文件再 cat。
坑19:glab mr create 内联 heredoc 让 REPL 解析崩溃
命令里内嵌 heredoc 直接 Unexpected EOF。处理:先用文件写 MR 描述,再 --description "$(cat /tmp/mrdesc.txt)"。
6. 收口 MR 清单
- 应用侧 MR !99(ugreenhome)→
feature/1.8.0:17 个*-bin升.1+ JXSegmentedView 回退源码(已合并); - cicd MR !35:同版本 zip 覆盖改为硬失败(必须 bump 版本);
- cicd MR !36(→ main):BLFD 碰撞守卫 + manifest JXSegmentedView skip + push-spec 不变量注释(已合并);
- 16 个旧的 library-evolution MR 已关闭;lottie-ios MR !4 已合并(4.6.0.3 tag 对齐)。
7. 验证结论
- 18 / 18
*-bin组件经远端 tag 流水线重发,sha256 一致; - 真机验证通过:UGIconButton 正常渲染、Lottie 正常播放、无 dyld
Symbol-not-found崩溃。
名词补充
- Library Evolution / Module Stability:Swift 通过
.swiftinterface描述模块 API,使消费端能跨编译器版本导入预编译框架的能力;BLFD 即开启该能力的编译开关。 - resilient 符号:开启 library evolution 后,module 内部符号可采用 resilient 形式,允许在不破坏二进制兼容的前提下扩展——这也是为何某些组件不能简单回退源码。
- Nexus raw 仓库 / 侧车文件(sidecar):Nexus 的 raw 类型仓库存放任意二进制文件;
.sha256侧车文件与 zip 一并上传,供pod install校验完整性。 --no-overwrite:pod repo push的防覆盖选项,配合「已存在即拒绝」预检,确保 Specs 中同一版本指向的制品不可被二次改写。