Firebase Auth iOS SDK 版本演进全解析：从 12.19.0 到 3.0.2 的变更史与源码级解读-港品优选

Firebase Auth iOS SDK 版本演进全解析：从 12.19.0 到 3.0.2 的变更史与源码级解读

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk

Firebase Auth 是 Firebase iOS SDK 中负责用户身份认证的核心模块，覆盖邮箱密码、手机号、OAuth 联邦登录、匿名登录、多因素认证（MFA）、TOTP 两步验证、App Check 集成等能力。本文以 FirebaseAuth/CHANGELOG.md 为骨架，逐版本梳理 12.x、11.x、10.x 直至 3.0.2 的完整变更记录，并结合仓库中 FirebaseAuth/Sources 的实际源码实现，解读每个重要变更背后的技术原理。读完本文，你将掌握 Firebase Auth 各版本的新增能力、破坏性变更、已知问题修复路径，以及这些变更在 SDK 源码中的落点，便于在升级时做出准确判断。

版本体系与文档约定

Firebase iOS SDK 中，Firebase Auth 的版本号与整个 Firebase 平台的发布版本保持同步（例如 12.19.0 对应 Firebase 12.19.0 发布线）。CHANGELOG 采用标准的分组标签格式：

[added]：新增 API、错误码或能力；
[fixed]：缺陷修复；
[changed]：行为调整、内部重构或依赖变更；
[deprecated]：标记弃用，通常在后续主版本移除；
[removed]：移除 API，往往伴随Breaking Change（破坏性变更）；
[feature]：重大功能引入（早期版本使用）。

需要特别留意的是，CHANGELOG 中多次出现"该修复不会进入 11.x.0 的 zip 与 Carthage 发行包，但从 11.y.0 起生效"的说明（如 11.5.0、11.6.0、11.2.0 中的若干条目）。这提示开发者：如果通过 zip 或 Carthage 方式集成 Firebase Auth，部分修复的落地版本会比 CocoaPods 与 Swift Package Manager 晚一个次版本，升级时应以目标发行渠道实际包含的内容为准。

12.x：并发安全、App Check 稳定性与全新 AsyncSequence 监听 API

12.19.0：App Extension 构建错误与随机登出修复

12.19.0 修复了四个关键问题：

App Extension 构建错误（#16583）：12.18.0 引入的回归导致AuthNotificationManager直接引用了UIApplication.shared，而 App Extension 中不允许访问该 API。当前源码中的处理方式是引入AuthNotificationApplication协议，通过applicationForDelegate属性间接获取UIApplication实例，并明确注释"keepsUIApplication.shared- which is unavailable in app extensions - out of this module"。使用 App Extension 集成的项目升级 12.19.0 即可解决编译失败。
App Check 交互下的持续崩溃（#16549）：部分 Swift 工具链（如 Flutter SDK 自带工具链）在生成 Swift 并发 thunk 时存在编译器缺陷，与 App Check 交互会触发崩溃。此修复通过规避该编译器 bug 实现。
iOS 15+ 设备锁定状态下的随机登出（#16498）：设备处于 prewarming（预热）阶段且处于锁定状态时，用户会被随机登出。这与 keychain 在设备锁定期间的访问策略直接相关——历史上 Firebase Auth 多次围绕 prewarming 与 keychain 数据保护做修复（见 9.0.0、9.2.0 条目），此版本进一步完善了该场景。
显式模块模式下的传递导入构建错误（#16563）：logger 中的传递导入（transitive import）在显式模块（explicit module）模式下会导致编译失败，已通过调整导入方式修复。

12.18.0：PhoneAuthProvider 测试模式与密码策略错误码

手机号认证测试模式与 MFA 的冲突（#16438）：当项目启用多因素认证（MFA）时，PhoneAuthProvider的测试模式逻辑（即appVerificationDisabledForTesting）会失效，表现为验证流程不按预期跳过。相关开关在源码中位于 AuthSettings.swift 的appVerificationDisabledForTesting属性。
verifyPhoneNumber无限递归崩溃（#16416）：某些工具链的 Swift 并发编译器缺陷导致verifyPhoneNumber陷入无限递归并崩溃，已通过规避该缺陷修复。
新增passwordDoesNotMeetRequirements错误码（#16462）：该错误码数值为17211，用于统一处理密码策略（password policy）校验失败，区别于传统的弱密码错误（weakPassword = 17026）。后端错误到客户端错误的映射位于 AuthBackend.swift（passwordDoesNotMeetRequirementsError），构建逻辑位于 AuthErrorUtils.swift。开发者可以借此区分"密码太短"与"不符合项目自定义密码策略"两种失败原因，从而给出更精准的提示文案。

12.16.0：Mac Catalyst 的 OAuth 登录 UI 修复

集成式 OAuth 登录 UI（integrated OAuth sign in UI）此前依赖已被弃用的UIScreen.main.bounds进行渲染（#16274），在 Mac Catalyst 下无法全屏展示。12.16.0 重构了渲染逻辑，不再依赖该 API，同时修复了 Catalyst 下 UI 不占满全屏的问题。
同时优化了缺少FirebaseApp.configure()时的错误提示（#16294），使其更准确地说明支持的初始化方式。

12.12.0：AsyncSequence 状态监听与并发修复

这是 12.x 中最重要的功能增强：

新增Auth.authStateChanges与Auth.idTokenChangesAsyncSequence 属性：这是基于 Swift 结构化并发（structured concurrency）的现代监听方式，用于替代传统的addStateDidChangeListener与addIDTokenDidChangeListener回调式 API。实现位于 Auth+Async.swift：
```
func monitorAuthState() async { for await user in Auth.auth().authStateChanges { if let user { print("User signed in: \(user.uid)") } else { print("User signed out.") } } }
```
源码细节值得关注：该序列底层通过AsyncStream<User?>包装addStateDidChangeListener，并在continuation.onTermination中自动移除监听器，实现了"迭代开始即注册、迭代结束即注销"的生命周期管理。第一个发射值始终是当前认证状态（可能为nil）。该 API 的可用性标注为 macOS 15.0+、iOS 18.0+、watchOS 11.0+、tvOS 18.0+、visionOS 2.0+，使用前请确认最低部署版本。
修复User.providerData的竞态条件（#15950）：并发读取 provider 数据可能返回不一致结果。
修复 Xcode 26.4（Swift 6.3）下的 release 构建崩溃（#15974）：Swift 回归导致async letteardown 阶段崩溃，仅影响 release 构建。

12.9.0 与 12.7.0：App Check 刷新与 Token 刷新收敛

12.9.0（#15372）停止了不必要的 App Check token 刷新。该问题自 11.0.0 引入：每次访问受保护 API 时若都触发 App Check 刷新，会带来不必要的网络开销与后端压力。
12.7.0（#15474）引入token 刷新收敛机制（TokenRefreshCoalescer），防止并发 token 刷新。源码实现是一个actor：当多个调用方（如 Storage、Firestore、自动刷新）同时请求刷新时，只发起一次网络请求，其余调用方等待并共享同一个刷新结果：
```
// 多个并发请求同时到达 Task { try await tokenRefreshCoalescer.coalescedRefresh(currentToken: token, ...) } // 1 Task { try await tokenRefreshCoalescer.coalescedRefresh(currentToken: token, ...) } // 2 Task { try await tokenRefreshCoalescer.coalescedRefresh(currentToken: token, ...) } // 3 // 只有 1 次 STS 网络调用，三个 Task 拿到同一个刷新后的 token
```
该实现还会在 token 已变化时丢弃旧的在途任务并重新发起刷新，失败时清空 pending 状态以便下次重试。

12.2.0 与 12.1.0：TOTP 支持 macOS 与二维码修复

12.2.0 将 TOTP 第二因子认证（时间型一次性密码）扩展至 macOS。相关类型如TOTPSecret、TOTPMultiFactorGenerator、TOTPMultiFactorInfo定义在 FirebaseAuth/Sources/Swift/MultiFactor/TOTP，其中 TOTPSecret.swift 的代码明确以#if os(iOS) || os(macOS)区分平台分支。
12.1.0 修复了生成的 TOTP URL 格式问题（#15128）：generateQRCodeURL(withAccountName:issuer:)生成的 URL 遵循 Google Authenticator 的 Key-Uri 格式otpauth://totp/{issuer}:{accountName}?secret=...&issuer=...&algorithm=...&digits=...，此前格式化问题导致 Google Authenticator 无法识别。

12.0.0：破坏性变更集中发布

12.0.0 是一次主版本升级，包含以下 Breaking Changes：

移除 Dynamic Links 相关 API：ActionCodeSettings.dynamicLinkDomain、AuthErrorCode.dynamicLinkNotActivated、AuthErrorCode.invalidDynamicLinkDomain全部移除。替代方案是 11.8.0 引入的ActionCodeSettings.linkDomain（详见下文）。
移除String类型productID的 Swift API：仅影响 Swift 客户端，必须改用AuthProviderID枚举（见 AuthProviderID.swift）。
TOTPSecret.openInOTPApp(withQRCodeURL:)标注@MainActor：在主 actor 或主线程之外调用时必须使用await。源码中该方法确实标记为@MainActor @objc(openInOTPAppWithQRCodeURL:)（TOTPSecret.swift），并且内部对 App Extension 场景做了保护——通过反射调用sharedApplication而非直接引用，避免扩展内崩溃。
简化了 Auth interop 的 completion handler 内存管理（#14962）。

11.x：稳定性回归修复与大版本过渡

11.x 版本线的主旋律是恢复 Firebase 10（及更早版本）的既有行为，解决 11.0.0 大规模重构（Swift 化改造）带来的兼容性问题。

11.6.0：reCAPTCHA Enterprise 与 currentUser 回归

新增 reCAPTCHA Enterprise 支持（#14114）：手机号认证的应用验证（app verification）可使用 reCAPTCHA Enterprise。配套要求见 11.9.0：使用 reCAPTCHA Enterprise 需要 reCAPTCHA Enterprise 18.7.0 或更高版本。
恢复 Firebase 10 的Auth.currentUser行为：11.x 早期版本中，启动阶段currentUser可能意外为nil。11.6.0 通过同步化（synchronizing）对currentUser的访问恢复旧行为。
恢复 Firebase 10 的解码行为（#14011）：Firebase 11 读取 Firebase 10 写入的数据时，User.providerData可能被错误解码为nil（尤其是有多个已关联 provider 的用户）。11.6.0 恢复旧解码行为。注意 zip 与 Carthage 发行包从 11.6.0 之后才包含此修复。

11.5.0：老版本升级登出问题

恢复 11.0.0 之前的解码行为（#14011），防止从 Firebase 8.10.0 或更早版本升级到 Firebase 11 时用户被登出。
恢复 Firebase 10 的 keychain 错误处理行为（#14067）：11.x 在取回 token 时改变了 keychain 错误处理策略，可能导致用户被意外登出。两个修复同样在 zip/Carthage 渠道延后到 11.6.0 生效。

11.4.0：MFA 相关崩溃修复

恢复 Firebase 10 行为：MFA 注册时忽略nildisplay name（#13856）。
修复 TOTP MFA 注册账户时的崩溃（#13880）。

11.3.0：keychain 同步查询与并发安全

恢复 Firebase 10 行为：当 auth state 设置为跨设备共享时，使用kSecAttrSynchronizablekey 查询 keychain（#13584）。这与 7.4.0 的跨设备同步 auth state 能力（useUserAccessGroup）相关。
网络层改用原生 Swift 类型（#13650）：避免 ObjC 桥接引发的坏内存访问崩溃，同时将同步工作移出共享的 Swift 并发队列。
恢复被中断的 reCAPTCHA / OIDC 登录流程的错误转发（#13645）。

11.2.0：多租户与 TOTP 修复

修复 Xcode 16 beta 中 Swift continuation 块的崩溃（#13480）。
修复 11.0.0 破坏的沙盒 APNS token 手机号认证（#13479）。
修复获取登录方式时因意外 nil 导致的崩溃（#13550）：此前可能同时返回nil数组与nilerror，现在改为返回空数组。
修复多租户项目中的会话持久化（#13565），该问题自 11.0.0 引入。
修复 TOTP MFA 的编码崩溃（#13591），zip/Carthage 渠道延后至 11.3.0。

11.1.0：AuthProviderID 自定义 provider 支持

修复AuthErrorCode的Swift.error协议一致性（#13430），使 NSError 与 Swift Error 桥接更顺畅。
为AuthProviderID增加自定义 provider 支持（#13429）：新增static func custom(_ value: String) -> Self构造方法。这是一个潜在破坏性变更——对 11.0.0 中AuthProviderID做了穷尽式（exhaustive）switch的代码需要增加分支。从源码看，AuthProviderID是一个Equatable的 struct，内建 provider 包括 apple、email、facebook、gameCenter、gitHub、google、phone，自定义 provider 通过custom(_:)包装任意 raw string。
修复 11.0.0 引入的手机号认证崩溃（#13470）：token 超时后隐式解包nilerror 导致崩溃。
修复 ObjC 的[OAuthProvider getCredentialWithUIDelegate]未在主线程回调 completion 的问题（仅 CocoaPods 与 SPM 渠道，zip/Carthage 延后至 11.2.0）。

11.0.0：Swift 化重构里程碑

11.0.0 是 Firebase Auth 全面 Swift 化（模块从 ObjC 迁移至 Swift 实现，源码位于 FirebaseAuth/Sources/Swift）的大版本：

引入AuthProviderIDSwift 枚举（#9236）替代String类型的 provider ID，同时弃用旧 API。
破坏性变更：ActionCodeInfo.email属性改为非可选。
修复 auth domain 匹配优先级：优先匹配firebaseapp.com而非web.app，即使服务端返回顺序相反（#7992）。
11.x 后续版本中反复出现的"恢复 Firebase 10 行为"类修复，正是本次大规模重构引发的兼容性回归的善后工作。

10.x：功能扩张期

10.x 版本线持续引入新能力：

10.21.0：修复 MFA resolver 使用错误 Auth 实例的问题（#12265），此前总是使用默认实例而非调用方指定的实例。
10.19.0：弃用updateEmail(to:)与fetchSignInMethods(forEmail:)（#12081）。
10.18.0：修复匿名账户无法关联邮箱密码凭据的问题（#11911）。
10.16.0：reCAPTCHA v2 认证流程支持自定义 auth domain（#7553）。
10.14.0：邮箱认证流程新增 reCAPTCHA 验证支持（#11231）。
10.13.0：修复 10.12.0 引入的 iOS App Extension 编译回归（#11537）。
10.12.0：新增 TOTP 第二因子注册与登录支持（#11261）——这是 TOTP 能力首次进入 Firebase Auth。
10.8.0：新增Firebase App Check 支持（#11056）与Sign in with Apple token 撤销支持（#9906）。
10.7.0：新增从 Sign in with Apple 凭据传递fullName的 API（#10068）。
10.6.0：修复未指定 tenantID 时用户仍被创建到特定租户的问题（#10748）；修复 MFA resolver 未关联正确 app 的问题（[#10690]）。
10.5.0：游戏中心签名验证改用 team player ID、game player ID 与 fetchItems（#10441）；避免 macOS 访问 Auth keychain 时弹出 keychain 对话框（[#10582]）——前提是应用已通过带 Keychain Sharing 能力的 provisioning profile 签名。
10.4.0：修复 MFA 中的 secure coding 漏洞（#10632）；处理阻塞云函数（blocking cloud function）返回的错误（#10628，对应错误码blockingCloudFunctionError = 17105）。
10.2.0：修复 linking/reauth 流程错误未被捕获的问题（[#10267]）；模拟器上手机号认证强制走 reCAPTCHA 验证流程（[#10426]）。
10.1.0：修复 MFA 手机号返回NULL的问题（#10296）。

9.x：keychain 与 Swift 互操作修复

9.5.0：修复手机号 MFA ID 获取错误（#10061）。
9.2.0：prewarming 问题改用捕获 keychain 错误的方式处理，弃用isProtectedDataAvailableAPI（#9869）。
9.0.0：破坏性变更——修复 ObjC 转 Swift 的 API 转换错误：getStoredUser(forAccessGroup:)由非可选返回值改为可选返回值，仅影响 Swift 用户（#8599）；修复 iOS 15 keychain 访问与 prewarming 相关问题（[#8695]）。

8.x：多租户、MFA 邮件链接与 App Check 前奏

8.14.0：开始为 Firebase Auth 收集 Firebase user agent（#9066）。
8.12.0：为getStoredUser(forAccessGroup:)补充 tvOS keychain 共享问题的文档与错误日志（#8878）；部分修复过期 ID token 问题（#6521）。
8.11.0：网络请求新增X-Firebase-GMPID头（#9046）；通用 OAuth provider 支持多租户（#7990）；macOS Extension 通过kSecUseDataProtectionKeychain访问共享 keychain（#6876）。
8.9.0：新增MFA 对邮件链接登录的支持（#8705）；改进错误日志（[#8704]）。
8.8.0：手机号认证超时未收到推送通知时，回退到 reCAPTCHA 应用验证（#8653）。
8.2.0：修复 email link、Game Center、手机号登录流程的 bug（#8196）。
8.0.0：修复设置 auth settings 时的崩溃（#7670）。

7.x：Auth Emulator、跨设备同步与多租户

7.8.0：修复首次启动时 auth state 共享问题（#7472）。
7.6.0：Auth Emulator 支持跨本地网络工作（#7350），便于真机联调；修复 watchOS 错误导入（[#7425]）。
7.4.0：设置回调 scheme 前先检查 reverse client ID 是否已配置为自定义 URL scheme（#7211）；新增跨设备同步 auth state 能力（#6924，即useUserAccessGroup，源码位于 Auth.swift）；email link 登录支持多租户（[#7246]）。
7.3.0：修复 Catalyst 下verifyPhoneNumber的浏览器问题（#7049）。
7.0.0：新增 Auth Emulator 支持（#6624）；移除一批带data字样的旧 API（dataForKey、fetchProvidersForEmail:completion:、signInAndRetrieveDataWithCredential:等）；全局变量FirebaseAuthVersionNum/FirebaseAuthVersionStr删除，改用FirebaseVersion()或FIRFirebaseVersion()。

6.x：功能奠基期（MFA、Apple、多租户首秀）

6.x 是 Firebase Auth 功能快速扩张的时期，当前 SDK 的诸多核心能力均发源于此：

6.9.0：新增多租户支持（#6142）；新增基础 watchOS 支持（[#4621]）；改进 Swift 中 completion handler 的 Xcode 补全体验。
6.8.0：修复多个 keychain 条目导致用户持久化失败的问题（#5906）；generic IDP 与手机号 reCAPTCHA 回退流程支持GOOGLE_APP_ID（[#6121]）。
6.7.0：为 Swift Package Manager 支持做源码重组（[#5856]），功能不变。
6.5.0：新增多因素认证（MFA）支持（#4823）。
6.4.0：新增 Sign in with Apple 支持（#4183）。
6.4.1：支持UISceneDelegate处理 URL 重定向（#4380）；修复 encoder 中的 rawNonce（[#4337]）。
6.3.0：新增联邦 provider 的链接（link）与重新认证（reauthenticate）方法（#3971）。
6.2.0：公开头文件暴露 OAuth credential 的secret（#3089）；修复 API key 在 keychain 中设置错误的问题（[#3239]）。
6.1.0：支持web.app作为 auth domain（#2959）。
6.0.0：新增单点登录（SSO）支持（[#2684]）；弃用reauthenticateAndRetrieveDataWithCredential:等旧 API；移除公开 API 中的pendingToken；改用GULAppDelegateSwizzler做 app delegate swizzling（[#2591]）。

5.x：OAuth、Game Center 与测试能力

5.4.0：新增 Generic IDP 支持（#2405），允许接入任意 OAuth2 身份提供方。
5.3.0：改用registerInternalLibraryAPI 注册到 FirebaseCore（#2137）。
5.2.0：新增 Game Center 登录（#2127）。
5.1.0：支持自定义 FDL 域名链接（#2121）。
5.0.3：新增FIRAuthErrorCodeMalformedJWT错误码（#1436，数值 18000）；改用 FirebaseAuthInterop 接口访问 FirebaseAuth（#1501）。
5.0.2：修复 JWT 时间戳解析错误（#1319）；修复匿名账户链接无密码邮箱账户时的升级问题（[#1383]）；修复使用已失效 NSURLSession 的异常（[#1261]）。
5.0.1：恢复 4.x 级别的 Extension 支持（[#1357]）。
5.0.0：新增手机号认证测试 API（绕过验证流程，#1192）；sign-in 与创建用户方法的回调签名改为提供AuthDataResult（包含 user 与 user info，[#1123]、#1186）；移除 GoogleToolboxForMac 依赖（[#1175]）；移除一批弃用 API。

4.x：手机号认证与无密码登录

4.6.0：新增getIDTokenResultWithCompletion:与getIDTokenResultForcingRefresh:completion:，回调返回AuthTokenResult（包含 ID token JWT 字符串与已解码的 payload claims，#1004）；新增updateCurrentUser:completion:（#1018）；当handleCodeInApp设为 false 而执行 email-link 认证时抛异常（[#931]）；支持向signInWithEmail:link:传入内嵌于登录链接中的 deep link（#1023）。
4.5.0：新增获取邮箱关联登录方式的方法；新增仅凭邮箱链接的无密码认证（Passwordless Authentication，[#1023] 相关的 email link 能力）。
4.4.4：修复 Xcode/CocoaPods 下CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF警告；完善FIRUser关于用户校验时机与失效用户处理机制的文档（#694）。
4.4.0：新增返回AuthDataResult对象的新 API（邮箱密码创建/登录、匿名登录、Custom Token 登录，[#1023]）。
4.2.0：新增使用智能 reCAPTCHA 验证应用的手机号验证 API。
4.1.0：支持原生处理 continue URL（如密码重置邮件）；支持设置语言代码；修复用户手机号未持久化的问题；优化启动时间（初始化移出主线程）；改进口令缺失错误提示。
4.0.0：新增手机号认证；新增通用 OAuth2 身份提供方支持；改进会话管理（自动刷新 token、检测会话失效并登出）；修复重认证误创建新账户的问题；auth state 监听仅在用户变化时触发；新增 ID token 变化监听器；弃用FIREmailPasswordAuthProvider改用FIREmailAuthProvider；弃用getTokenWithCompletion改用getIDTokenWithCompletion；Swift API 命名对齐 Swift 规范。

3.x：起步与稳定

3.1.1：处理发送 OOB action 邮件时的更多服务端错误（INVALID_MESSAGE_PAYLOAD、INVALID_SENDER、INVALID_RECIPIENT_EMAIL）。
3.1.0：新增处理邮件动作（验证邮箱、重置密码）的 FIRAuth 方法；修复 iOS 10.2 模拟器 keychain workaround 的移除逻辑；更好的密码缺失错误提示。
3.0.6：改用开源 GoogleToolboxForMac 与 GTMSessionFetcher。
3.0.5：绕过 iOS 10 模拟器 keychain 问题；修正邮箱密码登录的错误报告。
3.0.3：为所有方法补齐可能的错误码文档；是否匿名用户的判断与其他平台保持一致；已保存登录用户按 Firebase 项目隔离。
3.0.2：Initial public release（首次公开版本）。

升级指南与关键 API 迁移速查

综合 CHANGELOG 中的破坏性变更，给出以下升级核对清单：

升级到 12.0.0 之前：将ActionCodeSettings.dynamicLinkDomain迁移到 11.8.0 新增的linkDomain；将String型 provider ID 迁移到AuthProviderID枚举（注意 11.1.0 后对AuthProviderID的switch需包含custom分支）；为TOTPSecret.openInOTPApp(withQRCodeURL:)的@MainActor标注添加await。
升级到 11.0.0 时：ActionCodeInfo.email变为非可选；Swift 侧 provider ID API 全面迁移至AuthProviderID；同时关注 11.x 各次版本中"恢复 Firebase 10 行为"的修复是否已覆盖你的集成渠道（zip/Carthage 有延迟）。
升级到 9.0.0 时：Swift 代码中getStoredUser(forAccessGroup:)的返回值从非可选变为可选，需要处理nil情况。
升级到 7.0.0 时：移除旧版...AndRetrieveDataWithCredential:系列 API；FirebaseAuthVersionNum/FirebaseAuthVersionStr改用FirebaseVersion()。
密码策略开发：使用 12.18.0 引入的passwordDoesNotMeetRequirements（17211）区分策略失败与weakPassword（17026），在 AuthErrors.swift 中可以查到完整的错误码清单。
现代监听方式：iOS 18+/macOS 15+ 上优先使用authStateChanges与idTokenChangesAsyncSequence，替代回调式监听器。

企业官网建设流程全解析