还在用 Carthage 集成 Firebase?这 5 个坑我先替你踩了
还在用 Carthage 集成 Firebase?这 5 个坑我先替你踩了
上周帮朋友救一个 iOS 老项目,需求简单到离谱:把崩溃统计和推送接上 Firebase。
结果配置折腾了整整一个下午——不是代码写错,而是卡在“把库装进项目”这一步。
如果你也习惯用 Carthage,那这篇文章你最好先存下来。因为 Firebase 官方文档第一行就写着两个字:实验性。

一、先说清楚:Carthage 这条路,官方从没打算"转正"
Carthage 是什么?简单打个比方:CocoaPods 像一个全包式装修队,进门就把你家墙拆了重砌;Carthage 更像"只送建材、不管施工"的搬运工——帮你把依赖下好、编译成现成的框架,剩下怎么往项目里塞,全靠你自己动手。
很多人喜欢这份"不插手"的清爽,所以对 Carthage 一直有感情。
但真实情况是:早在 2019 年,Firebase 官方就在一个公开的需求帖里明确表态了——"既然 Swift Package Manager 才是未来,我们就不再计划正式支持 Carthage 了",会以实验性状态继续更新,直到迁移完成。
这一"临时"就是六七年。到今天,仓库里这条分发线依然挂着 experimental 的标签,而且只支持 iOS,macOS、watchOS、tvOS 想都别想。
换句话说,你不是在用一条正式产线,而是在用一个"好心人一直在帮忙维护的临时通道"。这个认知,能帮你少走很多弯路。
二、坑一:Analytics 是"必须带上"的,一个都不能少
第一个坑,最容易让人怀疑人生。
Carthage 的配置方式是按组件一条条列出,你想要什么就写什么,看起来特别自由。但官方文档里藏着一句话:FirebaseAnalytics 的二进制包必须始终包含,哪怕你的 App 压根不打算看数据报表。
这就好比你点了一份炒饭,店家说"必须搭一份汤",哪怕你不喝。
更麻烦的是第二条规矩:所有 Firebase 组件必须是同一个版本号。Firestore 用 13.0、Auth 用 13.1,看起来只差一个小版本,链接时很可能直接报错给你看。
所以正确的姿势不是"缺什么补什么",而是先把一条"全家桶清单"整整齐齐锁在一个版本上,再谈精简。
三、坑二:搬砖式的手工活,一步都不能漏
Carthage 编译完之后,真正的体力活才开始。以下这些活儿,全得靠手动:
- 把产物目录里的框架一个个拖进 Xcode,还要确认挂到了正确的构建目标上;
- 在链接参数里补上
-ObjC,不补的话,Analytics 相关的东西可能悄悄失效; - 千万不能把 Firebase 的框架加进 Carthage 那个自动拷贝阶段——因为 Firebase 里面装的是静态库,走了那一步反而会出问题;
- 删掉项目里遗留的那个总的 Firebase 框架;
- 有资源的组件,还要把资源包手动拖进"拷贝资源"环节;
- 视情况补一堆系统库,比如 C++ 标准库、sqlite3、StoreKit 之类。
还有一个细节特别能体现"半自动"的心酸:如果你想关掉广告标识符相关的支持,做法是别拷贝某一个特定的框架文件。想省掉用不上的 Swift 相关包?也是靠"别拷贝"来实现。
这不是配置,这是手工分拣。
四、坑三:遇到 Swift 链接报错?官方让你塞个空文件
这个坑我至今觉得离谱。
如果你的项目里出现 Swift 符号的链接错误,官方文档给的解决方案是:往项目里加一个空的 swift 文件。
对,就是加个啥也没有的空文件,"骗"一下编译器,让它把 Swift 运行时乖乖带进来。
我朋友当时的原话是:"我以为我在做工程,结果在跳大神。"
这种土办法能流传至今,恰恰说明了问题:这条分发线的打磨程度,和主推方案根本不在一个量级。
五、坑四:Crashlytics 是最深的那个坑
崩溃统计是很多人接 Firebase 的头号理由,但它在 Carthage 下最费劲。
正常流程,工具会自动帮你把调试符号上传到后台,崩溃堆栈能翻译成你看得懂的代码行号。
而在 Carthage 方案里,这套自动流程必须自己搭:手动下载两个脚本文件,放到工程目录,赋予可执行权限,在 Xcode 的构建阶段新建一个运行脚本,再把两个特定的输入文件路径填进去。
少填一个会怎样?构建可能过了,App 也能跑,但崩溃报表里全是天书般的十六进制地址。你等于装了个监控摄像头,却把镜头盖着。
更隐晦的是新版本 Xcode 的脚本沙箱机制:一旦开启,脚本读不到配置文件,就会报"取不到应用 ID"的错误。这时候还得回头补输入文件清单。
一句话总结:Crashlytics 在 Carthage 下不是集成,是手工打造一条流水线。
六、坑五:生态在"断供",这才是最要命的
前面几个坑,忍一忍都能过。但这一条,忍不了。
翻一翻仓库的版本变更记录,你会发现一条清晰的收缩曲线:
- 12.0 版本起,Dynamic Links 被整体移除,广告 SDK 也从 Firebase 的分发包里撤走;
- 12.0 版本起,老的 Vertex AI 组件下线,换成新的 AI Logic;
- 13.0 版本起,Google Sign-In 不再包含在压缩包和 Carthage 分发里,模型下载组件也被移除;
- 13.0 版本起,整个 Firebase 干脆不再通过 CocoaPods 发布新版本,只保留 SPM 和二进制分发;官方还给 CocoaPods 定了一个明确的时间点——2026 年 10 月之后不再发新版。
这意味着什么?意味着 Carthage 这条实验性通道,能拿到的"货"只会越来越旧、越来越少。
你现在能装上的已经是 13.1.1,但那不是因为它被精心维护,而是因为打包脚本顺手还在跑。哪天某次大版本改动了产物结构,这条线随时可能断。
七、什么时候该果断转 SPM?
我的建议很干脆:新项目别碰 Carthage,老项目找机会就迁。
理由不是"新技术更好",而是实打实的省事:
第一,配置从"清单"变成"勾选"。 在 Xcode 里添加包,把地址填进去,然后像点外卖一样勾选你要的产品就行,不用再手抄一长串地址。

第二,版本自动对齐。 所有组件天生同源同版本,那种"两个包差一个小版本导致链接失败"的玄学问题直接消失。
第三,Crashlytics 变成一个路径。 不用再手动下载脚本、赋予权限、拼装构建阶段,只要在构建脚本里写一个指向依赖缓存的路径就行——原本半小时的活,变成一分钟。
第四,能"瘦身"了。 从 13.0 开始,Firebase 支持按需裁剪功能。比如你的 App 完全不用数据库,就可以把这部分关掉,不必为用不上的东西付出体积代价。这在 Carthage 时代是想都不敢想的。
不过也说句公道话,迁 SPM 有两个门槛得先确认:一是新版本的 Firebase 对 Xcode 版本要求比较激进(目前要求 26.2 以上、Swift 6.2.3 以上);二是如果你要给 visionOS 用 Firestore,需要走源码分发的特殊开关。
还有一个细节值得记住:SPM 下依然要给 Analytics 加 -ObjC 链接参数。这个"祖传"要求,两套方案是一样的。
至于那些为了省编译时间、刻意选择预编译二进制的人——这份诉求完全合理。只是现在官方的答案不再是 Carthage,而是 SPM 的二进制依赖加缓存。方向变了,目的没变。
写在最后
Carthage 本身没做错什么,它只是没赶上苹果官方包管理器的时代浪潮。
而 Firebase 这种横跨十几个子系统、还包含闭源 Analytics 的巨型 SDK,注定只会把研发资源投向主线。实验性分支能活到今天,已经是社区和打包脚本一起撑着的体面。
真正要警惕的不是"要不要换工具",而是把项目的命脉,绑在一条官方明说不会转正的通道上。等技术债滚到某次大版本升级时一起爆发,代价就不是一个下午了。
最后想问问大家:你手上还有没有坚持用 Carthage 的老项目?迁移的时候最舍不得、或者最头疼的是哪一环?评论区聊聊,说不定能凑出一份避坑合集。