UgreenHome RN iOS 组件化与调试能力重建(阶段总结)

背景与目标 2026-10-29 至 11-02,我接手了 UgreenHome 主工程里一套陈旧的 RN(React Native)依赖栈,把目标定为三件事: 清理重复的实现入口与本地临时代码,统一走内网 Specs / GitLab / Nexus; 把可复用逻辑按单一职责拆成独立组件; 恢复原生符号调试与 Metro JS 调试,同时不破坏默认的离线与发布链路。 明确的不变量:不再为内部库新增「Debug/Release × 静态/动态」四套制品;不覆盖已发布 tag;所有产品变更走 MR;主工程保留业务组合,不追求机械地搬空目录。 本文是阶段收口记录。这里先说明一个原则:已发布、已合入、测试通过、真实设备运行通过,这四件事要分别记录,不能互相替代。下面凡是说到「已合入」「已发布」,都不代表所有真机业务场景已逐项通过。 推进路线 先清理、再合入:移除重复的 Runtime/Kit 接线与过时实验内容,清理无用分支、worktree、临时文件与部分缓存,保留未提交的业务改动。 建立远端组件边界:从 LocalPods / 主工程抽取可复用逻辑与资源,迁到 home/rn;测试随实现进入 test_spec,宿主只保留跨组件与设备集成测试。 治理依赖图:从显式 binary 选择推导传递 redirect,处理 Lottie、MMKVCore、ZIPFoundation 等同模块双实现问题,再扩展为调试源码闭包。 恢复 RN_DEBUG:统一安装入口、源码/Debug 变体选择、Metro 编译隔离与调试工具组件化。 继续下沉:通用 Debug 编辑器已发布,宿主 MR !262 已合入;UGreenRNComponents 0.1.0 已发布,WebView / Lottie 两个 subspec 已由宿主 MR !273 消费,原实现已从主工程删除。 阶段成果与真实边界 依赖单一真源:移除 LocalPods/UGreenRNRuntime 等重复清单,以 Podfile 的 rn_dependencies 统一维护版本与来源。 组件化切片:Platform、Transport、DeviceSettings、E-Ink、Debug 等职责已有独立组件。Transport 先下沉 HTTP callback gate / 取消策略,DeviceSettings 先下沉启动校验 / 手势 / codec,E-Ink 先下沉图片身份 / 重试 / 调度——不宣称整套 HTTP / MQTT / 业务桥已搬完。 ...

November 2, 2026

rn-runtime-ios Runtime 发布与接入踩坑复盘

最终结果 Runtime 最终发布版本:0.1.9.17 Lottie 内网修订版本:4.6.0.1 Runtime 发布流水线:Pipeline 3740 真机产物验证 Job:9486 成功 Runtime MR !22 已合并并完成发布 ugreenhome MR !8 已合并,Runtime 与 Lottie 依赖已同步升级 下面按「问题 → 根因 → 处理」的方式复盘,避免把教训写成流水账。 1. 依赖地址与 Lottie Podspec 依赖地址必须统一使用内网 GitLab 新域名,不能把 Runner 内部 IP(形如 192.168.x.x)写进 Podspec。这会造成环境耦合、证书 / SNI 问题,也让开发机与 CI 行为不一致。 Lottie 原始 4.6.0 已经发布,不能移动或覆盖旧 Tag。保留源码不变,仅修复 Podspec URL 时,应发布新的修订版本 4.6.0.1。 Specs 仓库中的版本、s.version、Git Tag 与 Runtime 依赖版本必须完全一致——这是后面一系列问题的总根。 2. 版本号与 Tag 任何会影响发布产物或 Podspec 的修复都要递增版本号,不能复用已经发布的 Tag; Tag 应从已经合并且验证通过的 main 创建,不要从未合并提交直接打发布 Tag; 发布前确认「Tag 规则、流水线 rules、版本文件」三者一致。「打了 Tag」不等于「publish-runtime 一定会触发」。 3. publish-runtime 未随 Tag 触发 首先检查 .gitlab-ci.yml 中 job 的 rules/only 是否匹配当前 Tag; 检查 Tag 是否属于 Protected Tag,以及触发者是否有对应权限; 发布 job 与普通构建 job 是两条独立链路:普通 CI 绿色不能证明发布 job 已创建或已执行; 修复后必须用新的版本和新 Tag 验证,不能移动旧 Tag 来「补跑」。 4. Specs Token 鉴权 SPECS_GIT_PASSWORD 必须是对 Specs 仓库具备写权限的有效 Token,并正确配置到 Runtime 项目的 CI/CD Variables。变量还要检查 Protected / Masked / Environment scope——受保护 Tag 上运行时,未受保护变量可能不可见。 ...

October 7, 2026

RN Runtime:Xcode 26 ↔ 27 二进制不兼容的原因

现象 用 Xcode 27 编译主工程时,若本地 RN Runtime 仍是 Xcode 26.6 打的预编译包,链接阶段失败: Undefined symbols for architecture arm64: method descriptor for Cxx.CxxPair.first.getter method descriptor for Cxx.CxxPair.second.getter 来源:NitroModules(AnyMap.o) 反向也成立:Xcode 27 的包拿到 Xcode 26.6 下去编,会缺另一组 Iterable / makeBorrowingIterator 相关符号。 结论(先看这个) 这不是某个编译参数(-fxxx / OTHER_SWIFT_FLAGS / BUILD_LIBRARY_FOR_DISTRIBUTION)能补丁过去的问题。 根因是: Swift 6.3.3(Xcode 26.6) → Swift 6.4(Xcode 27) 系统自带的 Swift–C++ 互通层(Cxx overlay)里,CxxPair 协议的 ABI 变了。预编译的 NitroModules 已经写死了对「旧 method descriptor」的引用;消费端换编译参数,补不出这些符号。 因此:同一套预编译 RN Runtime,不能跨 Xcode 大版本混用。 官方有痕迹,但没有面向 App 开发者的点名预警。官方提前说的是「C++ 互通还在变,用兼容模式保源码」,没有提前说「Xcode 26 的 Swift–Cxx 预编译包不能给 27 链接」。这是语言演进的必然结果,不是未公开的私有变更;发行说明漏了二进制兼容这一层。 ...

September 15, 2026