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-sdkFirebase 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 监听 API12.19.0App Extension 构建错误与随机登出修复12.19.0 修复了四个关键问题App Extension 构建错误#1658312.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 条目此版本进一步完善了该场景。显式模块模式下的传递导入构建错误#16563logger 中的传递导入transitive import在显式模块explicit module模式下会导致编译失败已通过调整导入方式修复。12.18.0PhoneAuthProvider 测试模式与密码策略错误码手机号认证测试模式与 MFA 的冲突#16438当项目启用多因素认证MFA时PhoneAuthProvider的测试模式逻辑即appVerificationDisabledForTesting会失效表现为验证流程不按预期跳过。相关开关在源码中位于 AuthSettings.swift 的appVerificationDisabledForTesting属性。verifyPhoneNumber无限递归崩溃#16416某些工具链的 Swift 并发编译器缺陷导致verifyPhoneNumber陷入无限递归并崩溃已通过规避该缺陷修复。新增passwordDoesNotMeetRequirements错误码#16462该错误码数值为17211用于统一处理密码策略password policy校验失败区别于传统的弱密码错误weakPassword 17026。后端错误到客户端错误的映射位于 AuthBackend.swiftpasswordDoesNotMeetRequirementsError构建逻辑位于 AuthErrorUtils.swift。开发者可以借此区分密码太短与不符合项目自定义密码策略两种失败原因从而给出更精准的提示文案。12.16.0Mac Catalyst 的 OAuth 登录 UI 修复集成式 OAuth 登录 UIintegrated OAuth sign in UI此前依赖已被弃用的UIScreen.main.bounds进行渲染#16274在 Mac Catalyst 下无法全屏展示。12.16.0 重构了渲染逻辑不再依赖该 API同时修复了 Catalyst 下 UI 不占满全屏的问题。同时优化了缺少FirebaseApp.configure()时的错误提示#16294使其更准确地说明支持的初始化方式。12.12.0AsyncSequence 状态监听与并发修复这是 12.x 中最重要的功能增强新增Auth.authStateChanges与Auth.idTokenChangesAsyncSequence 属性这是基于 Swift 结构化并发structured concurrency的现代监听方式用于替代传统的addStateDidChangeListener与addIDTokenDidChangeListener回调式 API。实现位于 AuthAsync.swiftfunc monitorAuthState() async { for await user in Auth.auth().authStateChanges { if let user { print(User signed in: \(user.uid)) } else { print(User signed out.) } } }源码细节值得关注该序列底层通过AsyncStreamUser?包装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.4Swift 6.3下的 release 构建崩溃#15974Swift 回归导致async letteardown 阶段崩溃仅影响 release 构建。12.9.0 与 12.7.0App 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.0TOTP 支持 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 格式问题#15128generateQRCodeURL(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 相关 APIActionCodeSettings.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.0reCAPTCHA 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 的解码行为#14011Firebase 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 错误处理行为#1406711.x 在取回 token 时改变了 keychain 错误处理策略可能导致用户被意外登出。两个修复同样在 zip/Carthage 渠道延后到 11.6.0 生效。11.4.0MFA 相关崩溃修复恢复 Firebase 10 行为MFA 注册时忽略nildisplay name#13856。修复 TOTP MFA 注册账户时的崩溃#13880。11.3.0keychain 同步查询与并发安全恢复 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 的编码崩溃#13591zip/Carthage 渠道延后至 11.3.0。11.1.0AuthProviderID 自定义 provider 支持修复AuthErrorCode的Swift.error协议一致性#13430使 NSError 与 Swift Error 桥接更顺畅。为AuthProviderID增加自定义 provider 支持#13429新增static func custom(_ value: String) - Self构造方法。这是一个潜在破坏性变更——对 11.0.0 中AuthProviderID做了穷尽式exhaustiveswitch的代码需要增加分支。从源码看AuthProviderID是一个Equatable的 struct内建 provider 包括 apple、email、facebook、gameCenter、gitHub、google、phone自定义 provider 通过custom(_:)包装任意 raw string。修复 11.0.0 引入的手机号认证崩溃#13470token 超时后隐式解包nilerror 导致崩溃。修复 ObjC 的[OAuthProvider getCredentialWithUIDelegate]未在主线程回调 completion 的问题仅 CocoaPods 与 SPM 渠道zip/Carthage 延后至 11.2.0。11.0.0Swift 化重构里程碑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.0reCAPTCHA 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.xkeychain 与 Swift 互操作修复9.5.0修复手机号 MFA ID 获取错误#10061。9.2.0prewarming 问题改用捕获 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 支持多租户#7990macOS 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.xAuth Emulator、跨设备同步与多租户7.8.0修复首次启动时 auth state 共享问题#7472。7.6.0Auth Emulator 支持跨本地网络工作#7350便于真机联调修复 watchOS 错误导入[#7425]。7.4.0设置回调 scheme 前先检查 reverse client ID 是否已配置为自定义 URL scheme#7211新增跨设备同步 auth state 能力#6924即useUserAccessGroup源码位于 Auth.swiftemail link 登录支持多租户[#7246]。7.3.0修复 Catalyst 下verifyPhoneNumber的浏览器问题#7049。7.0.0新增 Auth Emulator 支持#6624移除一批带data字样的旧 APIdataForKey、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 条目导致用户持久化失败的问题#5906generic 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.xOAuth、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绕过验证流程#1192sign-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改用getIDTokenWithCompletionSwift 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.2Initial 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:系列 APIFirebaseAuthVersionNum/FirebaseAuthVersionStr改用FirebaseVersion()。密码策略开发使用 12.18.0 引入的passwordDoesNotMeetRequirements17211区分策略失败与weakPassword17026在 AuthErrors.swift 中可以查到完整的错误码清单。现代监听方式iOS 18/macOS 15 上优先使用authStateChanges与idTokenChangesAsyncSequence替代回调式监听器。延伸阅读完整变更记录FirebaseAuth/CHANGELOG.md模块说明与开发指引FirebaseAuth/README.md公开 API 头文件FirebaseAuth/Sources/Public/FirebaseAuthSwift 实现源码FirebaseAuth/Sources/SwiftObjC 桥接层FirebaseAuth/Sources/ObjC单元测试FirebaseAuth/Tests/Unit 与示例工程 FirebaseAuth/Tests/SampleSwift认证状态跨设备共享与 keychain 说明可结合 FirebaseAuth/Sources/Swift/Storage/AuthKeychainServices.swift 与 FirebaseAuth/Sources/Swift/Auth/Auth.swift 继续深入。【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考