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

UgreenHome CocoaPods Specs / 镜像 tag 故障复盘

背景与现象 主工程使用内部 CocoaPods Specs 仓库。某些源码 pod 的 source.git 指向内部 GitLab 镜像;另一些第三方依赖由 *-bin spec 提供预编译 XCFramework。FCUUID-bin 的 spec 声明了对源码 pod UICKeyChainStore (~> 2.1.0) 的依赖,而主工程此前没有直接声明 UICKeyChainStore。 删除 iot/Podfile.lock 后运行 make -C iot pods,CocoaPods 重新解析传递依赖,选中了 Specs 中的 UICKeyChainStore 2.1.3。该 spec 指向镜像中不存在的 v2.1.1 tag,安装失败,典型报错是 fatal: Remote branch v2.1.1 not found in upstream origin。这发生在依赖解析、源码获取阶段,尚未进入 App 链接。 主工程 Podfile → FCUUID-bin 1.3.3.1 → UICKeyChainStore (~> 2.1.0) [传递源码依赖] → 无 lock 时选到 2.1.3 → source.tag = v2.1.1 [镜像不存在] → make pods 失败。 ...

October 21, 2026

UDC 镜像仓库迁移踩坑记录

背景 一次把 UDC 相关仓库从外部 GitLab 源迁到内网 GitLab + Nexus 的迁移,踩了十来个坑。本文把每个坑的「现象 → 根因 → 修复」记下来,方便后续再做类似镜像同步时直接对照。迁移目标是:把外部源(记为 gitlab-cloud)的仓库改写成指向内网 GitLab 的 podspec,并同步 Maven 产物到内网 Nexus。 名词解释 Pull Mirror(GitLab 原生镜像):GitLab 自带的仓库镜像功能,让镜像仓库与上游完全一致。 Nexus:内网私有仓库(Maven / raw 等),用来托管同步过来的二进制与 Maven 产物。 Protected 变量:GitLab CI 变量标记为 Protected 后,只在保护分支 / 标签上注入。 members/all:GitLab 查组成员接口,带 /all 才会包含从父组继承的成员。 一、GitLab 原生镜像根本没法用 一开始想直接用 GitLab 自带的 Repository Mirroring(pull mirror),结果它和「改写 podspec URL」的需求天然冲突:原生 pull mirror 会让镜像仓库与上游完全一致,等于把我们在内网侧做的 podspec URL 改写每次同步都覆盖回去。而且源仓库里的 podspec 仍带外部域名,我们用的同步 bot 是源项目的只读成员,push 回源会 403 “not allowed to upload code”——源仓库修不了。 ...

October 21, 2026

UG *-bin 重发与 BLFD 踩坑总结

适用范围 应用: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 版本各打一份二进制。 ...

October 18, 2026

把 GitHub 依赖迁移到内网 GitLab 的踩坑总结

背景 公司内网环境极差,外网访问几乎不可达,打包机几乎拉不到 GitHub 上的依赖,所以才把一部分依赖镜像到内网 GitLab,供打包机使用。加上部分仓库很大(如 Alamofire、lottie-ios),迁移过程中集中爆发了一批问题。 补充两点前置配置经验: 如果仓库是 Private 的,外部匿名拉取(不携带 token、cookie 等)会失败。需要在 General Settings - Visibility, project features, permissions - Package registry 下打开 Allow anyone to pull from Package Registry; 往 Pod Spec 仓库推送代码,需要 Maintainer 权限的账号,否则无法 push。 对于超大仓库,在网络环境差的情况下 git push --mirror 很容易出现 504 错误,只推我们用到的 tag 即可。 本次迁移踩坑总结 1. Shallow clone 无法推送 Tag GitLab 报 shallow update not allowed,需要先 git fetch --unshallow,再推送标签。 2. Git LFS 对象缺失 GitLab 会拒绝推送并提示 LFS objects are missing,必须同步并执行 git lfs push --all。 ...

October 12, 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

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

CocoaPods 源码导读:架构总览

本系列基于 CocoaPods 1.16.2(2026 年 4 月)源码进行分析。源码仓库由 15 个 Ruby Gem 组成,本文先从整体架构与职责拆分讲起,再以 pod install --repo-update 为主线绘制全景执行图,串起后续两篇专题的切入点。 系列目录: 架构总览(本文) 从命令到依赖求解 从下载到工程集成 一、CocoaPods 不是单一仓库 很多人以为 CocoaPods 就是一个 Ruby 项目,其实官方仓库 CocoaPods/CocoaPods 只是入口,真正的能力被拆成 15 个独立 gem,每个 gem 只做一件事。用 gem dependency cocoapods 会看到这样的依赖拓扑: graph TB subgraph "入口" A["bin/pod (CocoaPods gem)"] end subgraph "命令行框架" B["CLAide Command/Arg/Option DSL"] end subgraph "领域模型" C["Core Podfile/Podspec/Source/Lockfile"] end subgraph "依赖求解" D["Molinillo 回溯式 SAT 求解器"] end subgraph "下载" E["cocoapods-downloader Git/HTTP/SVN/Hg/SCP"] end subgraph "Xcode 工程读写" F["Xcodeproj pbxproj/xcconfig/workspace"] G["Nanaimo ASCII plist 解析"] end subgraph "插件与子命令" H["cocoapods-plugins"] I["cocoapods-trunk cocoapods-search cocoapods-try cocoapods-deintegrate"] end subgraph "辅助" J["cork 彩色输出"] K["nap 轻量 HTTP 客户端"] end A --> B A --> C A --> D A --> E A --> F F --> G A -.加载.-> H H -.调用.-> I A --> J I --> K 各 gem 的一句话职责: ...

May 2, 2026

CocoaPods 源码导读:从命令到依赖求解

本文是系列第二篇,基于 CocoaPods 1.16.2 源码。我们从 bin/pod 进场,走完 CLAide 的命令分发、Podfile 的 DSL 求值、Analyzer 的七步分析、Resolver + Molinillo 的回溯求解,最后交付 AggregateTarget/PodTarget 给下一篇讲的下载与集成。 上一篇:架构总览 · 下一篇:从下载到工程集成 运行示例贯穿全文:pod install --repo-update 一、bin/pod:16 行的入口 CocoaPods 的可执行文件非常薄,核心逻辑全在 require 'cocoapods' 之后的 Pod::Command.run: # CocoaPods/bin/pod : 24 if $PROGRAM_NAME == __FILE__ && !ENV['COCOAPODS_NO_BUNDLER'] ENV['BUNDLE_GEMFILE'] = File.expand_path('../../Gemfile', __FILE__) require 'rubygems' require 'bundler/setup' $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__) elsif ENV['COCOAPODS_NO_BUNDLER'] require 'rubygems' gem 'cocoapods' end STDOUT.sync = true if ENV['CP_STDOUT_SYNC'] == 'TRUE' require 'cocoapods' if profile_filename = ENV['COCOAPODS_PROFILE'] # 开 ruby-prof 做性能剖析 # ... reporter.new(RubyProf.profile { Pod::Command.run(ARGV) }).print(io) else Pod::Command.run(ARGV) end 这里有两个工程化细节值得留意: ...

May 2, 2026

CocoaPods 源码导读:从下载到工程集成

本文是系列第三篇,基于 CocoaPods 1.16.2 源码。上一篇我们停在 Analyzer 产出 AnalysisResult,本文继续走完 download_dependencies → validate_targets → generate_pods_project → integrate_user_project → write_lockfiles 这五个阶段。 上一篇:从命令到依赖求解 · 首篇:架构总览 一、全景:从 spec 到可编译的工程 先把本文要走的流程重新放一遍,让你带着地图读代码: flowchart TB A[AnalysisResult] --> B[download_dependencies] B -->|per pod| B1[PodSourceDownloader] B1 -->|命中| C1[Downloader::Cache] B1 -->|未命中| C2[cocoapods-downloader Git/HTTP/SVN/...] C2 --> C3[rsync → Pods/<name>/] B -->|per pod| B2[PodSourceInstaller] B2 --> B3[PodSourcePreparer prepare_command] B2 --> B4[PodDirCleaner 按 spec.source_files 裁剪] B --> D[validate_targets TargetValidator#validate!] D --> E[generate_pods_project] E --> E1[ProjectCacheAnalyzer 增量识别要重生成的 target] E --> E2[SinglePodsProjectGenerator#generate!] E2 --> E21[FileReferencesInstaller] E2 --> E22[PodTargetInstaller] E2 --> E23[AggregateTargetInstaller] E2 --> E24[xcconfig / modulemap / umbrella / info.plist / dummy.m] E --> E3[PodsProjectWriter#write! 写盘前触发 Podfile post_install] E --> F[integrate_user_project] F --> F1[create_workspace 写 .xcworkspace] F --> F2[deintegrate_removed_targets] F --> F3[TargetIntegrator#integrate! xcconfig / frameworks / scripts] F --> G[write_lockfiles] G --> G1[Podfile.lock] G --> G2[Pods/Manifest.lock] G --> H[perform_post_install_actions plugin post_install hook] 对应的 Installer#install! 片段: ...

May 2, 2026