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

GitLab SAST 在 ARM64 Runner 上的故障复盘

背景与目标 把 Semgrep SAST 接到 iOS 工程的 CI 上,原本的扫描 job 一直跑不通。本文记录从 Rosetta 崩溃到原生 ARM64 镜像上线的全过程,以及其间踩到的十几个坑。结论是:本机 / 流水线显示「非阻断成功」都不算验收通过,真正的完成标准是——正式 job 执行成功、新报告有效、GitLab 解析成功、目标分支配置一致。 名词解释 SAST(Static Application Security Testing,静态应用安全测试):不运行程序,靠扫描源码发现安全缺陷。 Semgrep:一款开源的静态分析 / SAST 引擎,GitLab 官方 SAST analyzer 底层就用的它。 Rosetta:Apple 在 ARM64 macOS 上转译运行 AMD64 二进制的兼容层;转译路径异常时会有看不懂的分配错误。 ARM64 / AMD64:两种 CPU 指令集架构。混用会导致需要转译,转译层出问题是本次故障根源。 gl-sast-report.json:GitLab SAST 的标准报告文件,有官方 schema 校验。 最终结果(验收口径) 修复后,正式 semgrep-sast job 切换到固定 digest 的原生 ARM64 镜像。正式 job(Runner 13 上)成功运行;285 条规则扫描 2209 个文件,产生 111 条原始发现;gl-sast-report.json 状态为 success 并通过官方 schema 校验;服务端确认扫描 SUCCEEDED、errors=[]。 ...

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

Crash 收集治理:从吞异常到 iOS 27 CrashReportExtension

现状:崩溃根本送不到后台 P0 — 崩溃根本送不到 SDK 1. UHAvoidCrash 把 NSException 吞了(最严重) AppDelegate.swift:48 无条件调用 AvoidCrash.makeAllEffective()。它 swizzle 了 NSArray / NSDictionary / NSObject 系列方法并包在 @try/@catch 里,异常被捕获后只发一个 AvoidCrashNotification,永远不会走到任何 uncaught exception handler。数组越界、插 nil 这类 iOS 最高频的崩溃,Bugly 和 Crashlytics 都收不到。AppDelegate.swift:182 的弹窗还是 #if UGDEBUG 门控的,线上连痕迹都没有。 2. UGLog 装了不链式的 uncaught handler UGLog.swift:212 的 NSSetUncaughtExceptionHandler 在 AppDelegate:61 安装,捕获后只写日志、不转发给前一个 handler。它是三者中最早装的,所以实际会被 Crashlytics / Bugly 覆盖;但 Bugly 在 AppDelegate:274 最后启动,它是否把 handler 链回 Crashlytics,源码里看不出来。这意味着 Crashlytics 可能整条链路被 Bugly 顶掉。这个必须实测:Release 包强制崩一次,同时看两个后台。 P1 — Bugly 数据基本不可用 3. Bugly 没有 dSYM 上传:全仓库只有 ${PODS_ROOT}/FirebaseCrashlytics/run(project.pbxproj:692),没有任何 buglySymbol / 上传脚本。Bugly 上的堆栈会是纯地址。 ...

September 17, 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

IoT 设备通信基础:配网、MQTT 与 P2P 穿透

配网:把 Wi-Fi 告诉设备 配网的核心目的只有一个:安全地把家庭 Wi-Fi 的 SSID 和密码告诉硬件设备。设备出厂时并不知道家庭网络,手机作为用户侧入口,承担「转交凭据」的角色。下面是几种主流方式,从最常见到更先进。 1. AP 模式(热点模式) 最经典、最通用的备选方案。 设备首次通电后自身创建 Wi-Fi 热点(名称常类似 XXX-Camera_XXXX); 手机在 Wi-Fi 列表里连上这个热点(提示「无法提供互联网访问」是正常的); App 检测到已连设备,提供界面让用户选择家庭 Wi-Fi 并输入密码; App 通过这条临时本地连接把 SSID / 密码发给设备; 设备关闭热点,用收到的密码去连家庭路由器,成功后配网完成。 优点:通用性强,几乎所有智能硬件都支持,不依赖路由器特殊功能,稳定性高。 缺点:用户需手动切换 Wi-Fi,过程中手机无法上网,体验不流畅。 2. Smart Config(一键配网) 目前体验最好的主流方式。 设备通电后进入混杂模式,监听空气中所有无线数据包; 用户在 App 输入家庭 Wi-Fi 密码后,手机用 UDP 广播将 SSID / 密码加密后,打包在数据包的长度里发送——像摩斯电码,通过长度变化传信息; 设备虽无法解密内容,但能「听」到数据包的长度规律,从中破译出 SSID 和密码; 设备主动去连家庭 Wi-Fi,并通知 App 配网成功。 优点:无需切换 Wi-Fi,全程在 App 内操作,体验极佳。 缺点:无线环境复杂(干扰多、2.4G / 5G 同名)时成功率可能降低;安全性相对 AP 模式稍低(信息已加密,但存在被嗅探的理论风险)。 3. 声波配网 常见于无屏幕设备(智能音箱、家电)。手机把 Wi-Fi 信息编码成高频 / 低频声波,设备用麦克风接收解码。 ...

September 10, 2026

网络 / 代理 / Gradle 问题修复记录

环境 Clash Verge Rev(混合端口 7897),全局代理在 ~/.zshenv; 两个机场订阅; 涉及内网域名 ugreeniot.com、ugreensmart.com,以及一台内网 Gradle 私服(形如 192.168.75.x)。 问题与修复 1. Android Studio Gradle 同步失败 现象:拉 kotlin-compiler-embeddable-2.4.0.jar(57 MB)失败,走代理 3m19s 只下 5.79 MB(29 kB/s),直连仍 3m48s 失败。 根因:AS 的 HTTP Proxy 设置不影响 Gradle daemon(Gradle 只看 gradle.properties / init script)。repo.maven.apache.org 走 Cloudflare CDN,Gradle 并发 HTTP/2 在国内频繁 RESET。curl 单连接 4.4 MB/s 正常,但 Gradle 不行。阿里云镜像 17.5 MB/s。 修复:新增 init.d 脚本把 3 个仓库换阿里云镜像(只影响本机,不污染团队项目)。验证 BUILD SUCCESSFUL。 坑:换源后报 Could not find xxx.klib——镜像文件其实是全的(md5 一致),真因是之前超时留下的半截缓存(pom / module 下了,klib 没下)。解决:删 metadata + 坏 artifact 目录,保留 1.1 GB 有效文件,不要用 --refresh-dependencies 或整个删 caches。 ...

September 7, 2026