从 CocoaPods 迁移

CocoaPods 宣布，他们将于 2026 年 12 月进入只读模式，之后将无法再发布新的 pod 版本。以下部分将详细介绍此变更，并说明如何将应用迁移到其他安装管理器。

概览

  • 具体变化CocoaPods 将进入只读状态，Firebase 将于 2026 年 10 月停止向 CocoaPods 发布新版本。
  • 我的应用会损坏吗？不会。现有版本的 Firebase 库将无限期地保留在 CocoaPods 注册表中，使用这些 CocoaPod 版本的应用将继续正常运行。
  • 为什么要迁移？如需继续接收最新功能、性能改进和关键修复，您应迁移使用 Swift Package Manager 或手动安装。

为配合 CocoaPods 的公告，Firebase 将于 2026 年 10 月停止向 CocoaPods 发布新版本。这些更改会影响以下所有 pod 及其子依赖项：

受影响的 Firebase pod
Firebase FirebaseAuth FirebaseInstallations
FirebaseABTesting FirebaseCore FirebaseMessaging
FirebaseAI FirebaseCrashlytics FirebaseMLModelDownloader
FirebaseAILogic FirebaseDatabase FirebasePerformance
FirebaseAnalytics FirebaseFirestore FirebaseRemoteConfig
FirebaseAppCheck FirebaseFunctions FirebaseStorage
FirebaseAppDistribution FirebaseInAppMessaging

此外，这些更改还会影响封装了原生 Firebase Apple SDK 的所有 Firebase 分发版本，包括 Firebase Unity SDK、Firebase C++ SDK 和 FlutterFire。

迁移 Apple 应用

如果您要将其他（非 Firebase）依赖项从 CocoaPods 迁移，请注意，行业最佳实践是为整个项目使用单一安装方法。在同一目标中混用 CocoaPods 和 Swift Package Manager (SPM) 可能会导致复杂的依赖项循环和 build 错误。如果您的非 Firebase 依赖项尚不支持 SPM，那么在迁移过程中，使用手动安装 Firebase 库是整合工作流程的最稳定方式。

Swift Package Manager (SPM)

什么是 Swift Package Manager？

Swift Package Manager (SPM) 是 Apple 用于管理代码分发的原生工具。它直接集成到 Xcode 中，无需使用 CocoaPods 等外部 CLI 工具，并且通过移除大多数标准配置所需的 .xcworkspace，简化了项目结构。

迁移为使用 Swift Package Manager

对于大多数项目，迁移到 Swift Package Manager 不需要更改应用代码，除非您的项目具有自定义 Xcode 配置或依赖项，并且这些配置或依赖项大量使用 CocoaPods 安装脚本。

下面介绍如何从 CocoaPods 迁移到 Swift Package Manager：

  1. 验证应用的每个依赖项是否都支持 Swift Package Manager。 所有 Firebase 库都支持 SPM，但您需要在非 Firebase 依赖项的 GitHub 代码库或产品页面中查看它们是否支持 SPM。如果您的某些非 Firebase 依赖项不支持 SPM，那么使用手动安装（而非 SPM）是从 CocoaPods 迁移的最稳定途径。
  2. 关闭 Xcode，然后从项目中移除 CocoaPods：
    1. 在项目目录中运行以下命令，卸载 CocoaPods 依赖项： 
      pod deintegrate
    2. 删除 CocoaPods 生成的 .xcworkspace。
  3. 在 Xcode 中，使用 Swift Package Manager 依赖项更新项目：
    1. 通过 Xcode 打开项目的 .xcodeproj 文件。
    2. 使用 File > Add Package Dependencies 重新添加应用依赖项。
  4. 添加 Firebase 软件包后，您可以通过在 Xcode 中前往项目设置，选择应用目标，然后在 Frameworks, Libraries, and Embedded Content 下更新库，来更新您依赖的 Firebase 库。

如需详细了解如何在 Xcode 中使用 SPM，请参阅 Apple 文档。

手动安装

什么是手动安装？

手动安装涉及下载 Firebase.zip 归档文件，其中包含所有 Firebase 产品的预编译 XCFramework。这样一来，您无需使用依赖项管理器，即可直接将特定 SDK 拖放到 Xcode 项目中。

迁移到使用手动安装

  1. 关闭 Xcode，然后从项目中移除 CocoaPods：
    1. 在项目目录中运行以下命令，卸载 CocoaPods 依赖项： 
      pod deintegrate
    2. 删除 CocoaPods 生成的 .xcworkspace。
  2. 按照我们的安装指南中的步骤，手动将 Firebase 添加到您的项目中。

迁移 Unity、C++ 和 Flutter 应用

Firebase Unity SDK 和 FlutterFire

大多数 Unity 和 Flutter 开发者无需采取任何行动。在 Unity 或 Flutter 上更新到最新版本的 Firebase 会自动将 Apple 平台上的底层依赖项管理器迁移到 Swift Package Manager。

请注意，如果您通过 CocoaPods 管理非 Firebase 依赖项，可能需要手动迁移这些依赖项。

Firebase C++ SDK

如果您之前是通过 CocoaPods 包含底层 iOS 依赖项，则可以按照上述迁移说明更新 Firebase CocoaPod 依赖项，以改用 Swift Package Manager。

常见问题解答

我需要在 2026 年 10 月之后继续使用 CocoaPods。如何让应用保持运行状态？

您可以选择使用旧版 Firebase pod，也可以从 GitHub 复制 Firebase podspec 并将其托管在您自己的规范代码库中。

无论哪种情况，我们都建议您尽快迁移出 CocoaPods。在 2026 年 10 月停止支持 CocoaPods 之后，我们将不再提供直接从 podspec 安装 Firebase 的官方支持。如果您选择自行托管 podspec，则需要负责确保它们保持最新状态。

为什么 CocoaPods 可以发布到 2026 年 12 月，但对 CocoaPods 的支持却将于 2026 年 10 月终止？

我们之所以选择 10 月，是为了确保发布到 CocoaPods 的最终版本在 12 月注册表锁定之前是稳定的。此时间表可提供必要的缓冲时间，以便安全地协调这些最终更新，并确保依赖于原生 SDK 但发布周期延迟的跨平台 SDK 有充足的时间来准备自己的版本。

如果不更新，我的应用会停止运行吗？

不会，此弃用只会影响未来版本的 Firebase 库。CocoaPods 中的现有版本仍可安装，使用这些 pod 版本的已部署应用不会受到影响。

这会影响项目结算吗？

不需要

在迁移到 Swift Package Manager 后编译项目时，我收到“FirebaseLibrary not found”错误。如何解决这个问题？

确保您已将 Firebase 软件包添加到 Xcode 项目中。

添加 Firebase 软件包时，Xcode 会提示您将 Firebase 框架添加到应用的 build 目标中。如果您在此步骤中忘记添加某个框架，可以随时在目标的设置中，通过 Build Phases > Link Binary with Libraries 添加该框架。如果您的项目包含多个目标，请确保已将 Firebase 添加到正确的目标。

此过渡会中断我的 CI/CD 流水线吗？

不会，运行 pod install 或 pod update 的流水线将继续适用于现有版本。不过，它们不会提取 2026 年 10 月之后发布的所有新的 Firebase 库更新。