local_auth 3.x 版本演进与 API 迁移指南从 PlatformException 到 LocalAuthException 的结构化错误处理【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packageslocal_auth是 Flutter 团队维护的本地认证插件用于在设备本地完成指纹、人脸等生物识别以及 PIN、图案、密码等设备凭据认证。本指南以 packages/local_auth/local_auth/CHANGELOG.md 为骨架梳理该插件从 0.x 到 3.x 的完整演进脉络重点剖析 2.0.0 联邦化架构迁移与 3.0.0 破坏性变更结构化异常体系与认证参数重构并给出可落地的升级迁移清单。读完你将掌握新旧 API 的对应关系、LocalAuthExceptionCode全部错误码的业务含义、各平台Android/iOS/macOS/Windows的支持边界与配置要求以及如何把旧代码平稳迁移到local_auth3.x。一、版本演进总览一条从单体插件到联邦架构的升级之路CHANGELOG 完整记录了插件自 0.0.1 初始发布以来的每一次变更。按关键节点可划分为四个阶段阶段版本区间里程碑起步期0.0.1 ~ 0.2.1初始发布支持stickyAuthFace ID 消息支持Android SDK 27 模板AndroidX 与安全升级期0.3.0 ~ 0.6.35新增canCheckBiometrics/getAvailableBiometricsAndroidX 迁移androidx Biometric要求FragmentActivity新增LockedOut/PermanentlyLockedOut错误码v2 embeddingstopAuthentication空安全与联邦化期1.1.0 ~ 2.3.0null safety支持 PIN/密码/图案2.0.0 迁移到 federated architecture2.1.0 增加 Windows 支持2.2.0 切到local_auth_darwin2.3.0 增加 macOS 支持3.x 重构期3.0.0 ~ 3.0.2结构化异常体系认证参数重构平台支持线整体上移Android API 24 / iOS 13.0从 pubspec.yaml 可以看到当前 3.0.2 的联邦架构形态local_auth本体只负责聚合 API通过default_package委托给四个 endorsed 实现包——local_auth_android、local_auth_darwiniOS/macOS 共用、local_auth_windows底层能力由local_auth_platform_interface定义契约。二、3.0.0 破坏性变更深度解析3.0.0 是 CHANGELOG 中标注BREAKING CHANGES最重的一次发布同时将最低 SDK 要求提升至 Flutter 3.29 / Dart 3.7并明确 Android 低于 API 24、iOS 低于 13.0 不再受支持。核心变更有两项。2.1 以 LocalAuthException 取代 PlatformException3.0.0 之前大多数失败场景抛出的是平台层的PlatformException调用方只能靠解析错误码字符串或消息文本来区分失败原因结构脆弱且难以做类型化处理。3.0.0 起绝大多数失败改为抛出LocalAuthException携带类型化的LocalAuthExceptionCode枚举值。在 auth_exception.dart 中LocalAuthException被定义为不可变异常包含三个字段code失败类型LocalAuthExceptionCodedescription人类可读的失败描述可空details附加细节可空LocalAuthExceptionCode目前定义了 15 个语义明确的错误码auth_exception.dart每个都有明确的业务含义错误码触发场景authInProgress上一次认证的 Future 尚未完成不能并发启动新认证uiUnavailable需要展示 UI 但无法展示如 Android 上没有可用 ActivityuserCanceled用户主动取消认证timeout设备特定超时导致取消systemCanceled系统事件取消如认证期间应用被切到后台noCredentialsSet设备既未录入生物特征也未配置密码/PIN/图案等回退凭据noBiometricsEnrolled设备具备生物识别能力但未录入任何生物特征noBiometricHardware设备没有生物识别硬件biometricHardwareTemporarilyUnavailable硬件暂时不可用被其他应用占用、蓝牙硬件未配对等temporaryLockout失败次数过多认证被暂时锁定稍后可重试biometricLockout生物识别被锁定需先用其他认证方式解锁userRequestedFallback用户通过系统 UI 选择了回退认证方式deviceError设备级错误细节见descriptionunknownError未知或意外错误注意枚举的演进承诺CHANGELOG 与源码注释均声明未来新增枚举值不视为破坏性变更因此客户端不应假设可以穷举匹配所有错误码务必保留default或其他兜底分支。对应 README 中的标准处理模式packages/local_auth/local_auth/README.mdimport package:local_auth/local_auth.dart; // ··· try { final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, ); // ··· } on LocalAuthException catch (e) { if (e.code LocalAuthExceptionCode.noBiometricHardware) { // Add handling of no hardware here. } else if (e.code LocalAuthExceptionCode.temporaryLockout || e.code LocalAuthExceptionCode.biometricLockout) { // 提示用户稍后重试或用其他认证方式解锁 } else { // 其他错误兜底处理 } }LocalAuthException与LocalAuthExceptionCode由 lib/local_auth.dart 从local_auth_platform_interface统一 re-export客户端只需导入package:local_auth/local_auth.dart即可使用无需额外依赖。2.2 认证参数重构stickyAuth 与 useErrorDialogs 的去留3.0.0 第二项破坏性变更是把authenticate中散落的AuthenticationOptions拆解为直接命名参数。对照关系如下AuthenticationOptions.stickyAuth→ 直接参数persistAcrossBackgroundingAuthenticationOptions.useErrorDialogs→无替代。错误处理 UI 应由插件调用方自行决定开发者需用新的结构化错误码来识别并处理原本由原生对话框承载的失败模式从 src/local_auth.dart 可以看到 3.x 的完整方法签名Futurebool authenticate({ required String localizedReason, IterableAuthMessages authMessages const AuthMessages[ IOSAuthMessages(), AndroidAuthMessages(), WindowsAuthMessages(), ], bool biometricOnly false, bool sensitiveTransaction true, bool persistAcrossBackgrounding false, })参数语义均来自源码 doc 注释localizedReason必填展示给用户的认证提示文案不能为空1.1.4 起加入非空断言authMessages各平台系统对话框的自定义文案默认覆盖 iOS/Android/Windows 三端biometricOnly为true时禁止回退到 PIN、图案、密码等非生物认证。README 明确提示 Windows 不支持此选项因为 Windows Hello 底层 API 无法选择认证方式sensitiveTransaction默认true是否启用平台特定防护例如 Android 人脸解锁识别成功后弹出确认对话框确保用户确有解锁意图persistAcrossBackgrounding默认false移动平台上认证可能因应用进入后台而被系统取消例如来电打断设为true后插件会等待应用回到前台并自动重试认证直到新尝试完成才返回。实现层的关键细节3.x 的authenticate在内部把参数组装为AuthenticationOptions后转交LocalAuthPlatform.instance其中useErrorDialogs被硬编码为false——源码注释明确说明这是遗留选项3.x 兼容实现应始终假定其为falsesrc/local_auth.dart。对应的AuthenticationOptions字段定义在 auth_options.dart。三、2.0.0 联邦化架构迁移一次影响深远的 API 重塑3.0.0 之前最重要的里程碑是 2.0.0——插件从单体结构迁移到federated architecture联邦架构平台相关代码拆分到独立实现包local_auth本体通过LocalAuthPlatform接口分发调用。这一点在 local_auth_test.dart 中得到验证——所有测试都基于MockLocalAuthPlatform替换LocalAuthPlatform.instance来验证方法转发例如authenticate测试断言平台层收到的正是默认的三端AuthMessages与AuthenticationOptions(useErrorDialogs: false)local_auth_test.dart。3.1 移除 authenticateWithBiometrics2.0.0 起已废弃的authenticateWithBiometrics被彻底删除统一使用authenticate。这意味着一份调用代码即可同时覆盖生物识别与设备凭据认证无需再区分入口。3.2 BiometricType 扩展 strong / weakBiometricType枚举在原有face、fingerprint基础上新增strong与weak用于表达认证的强度等级。应用代码需要相应处理这些新值。README 同时强调生物特征类型是设备相关、平台相关的未来还可能继续增加因此优先只检查是否录入了某种生物特征列表非空而不是依赖具体类型final ListBiometricType availableBiometrics await auth.getAvailableBiometrics(); if (availableBiometrics.isNotEmpty) { // 已录入某种生物特征 } if (availableBiometrics.contains(BiometricType.strong) || availableBiometrics.contains(BiometricType.face)) { // 特定类型可用——谨慎使用此类精确判断 }3.3 authenticate 参数形态变化2.0.0 示例2.0.0 的 CHANGELOG 给出了迁移前后的对照示例// 旧方式 Futurebool authenticate( localizedReason: localized reason, useErrorDialogs: true, stickyAuth: false, androidAuthStrings: const AndroidAuthMessages(), iOSAuthStrings: const IOSAuthMessages(), sensitiveTransaction: true, biometricOnly: false, ); // 新方式2.0 时代 Futurebool authenticate( localizedReason: localized reason, authMessages: const AuthMessages[ IOSAuthMessages(), AndroidAuthMessages() ], options: const AuthenticationOptions( useErrorDialogs: true, stickyAuth: false, sensitiveTransaction: true, biometricOnly: false, ), );2.0 时代平台相关文案从androidAuthStrings/iOSAuthStrings两个独立参数收敛为统一的authMessages列表到 3.0 又进一步把options展开为命名参数同时移除useErrorDialogs。演进方向始终是让接口更扁平、让错误处理更结构化、让平台定制更内聚。四、平台支持矩阵与系统要求演进CHANGELOG 记录了各平台支持逐步补齐的过程当前支持矩阵如下README.md平台最低要求AndroidSDK 24iOS13.0macOS10.15WindowsWindows 10关键演进节点2.1.0新增 Windows 支持基于 Windows Hello故不支持biometricOnly2.2.0iOS 的 endorsed 实现切换到local_auth_darwinmacOS 亦由其承担iOS 11 不再支持直接导入local_auth_ios获取认证文案的客户端需把依赖和 import 改为local_auth_darwin其余无需改动2.3.0macOS 获得 endorsed 支持3.0.0Android API 24、iOS 13.0 不再支持3.0.1README 改为链接到各实现包的 setup 说明并反映最新支持版本使用旧版本 Flutter 构建的应用会继续解析到兼容版本的平台实现3.0.2澄清getAvailableBiometrics关于 iOS 权限要求的文档——iOS 上即便设备已录入生物特征若应用未获授权这些特征也可能不可用最低 SDK 提升至 Flutter 3.38 / Dart 3.10。Android 侧的接入要求在 local_auth_android/README.md 中有完整说明三条硬性配置Activity 必须是FragmentActivity使用FlutterActivity的应用需在AndroidManifest.xml改为FlutterFragmentActivity自定义 Activity 则让MainActivity继承io.flutter.embedding.android.FlutterFragmentActivity这一要求自 0.5.0 引入 androidx Biometric 起生效声明权限AndroidManifest.xml中加入uses-permission android:nameandroid.permission.USE_BIOMETRIC/2.1.1 起由废弃的USE_FINGERPRINT替换主题兼容LaunchTheme的 parent 必须是合法的Theme.AppCompat主题如Theme.AppCompat.DayNight否则 Android 8 及以下会崩溃2.1.4 补充文档说明。五、从 CHANGELOG 读懂关键实现演变5.1 错误码体系的两次进化当前结构化错误码体系并非一蹴而就0.5.1新增LockedOut与PermanentlyLockedOut两个错误码用于表达锁定场景同时修复了authenticateWithBiometrics在生物识别对话框关闭前不返回结果的问题这一对错误码在 3.x 中被细化为temporaryLockout暂时锁定稍后可重试与biometricLockout生物识别锁定需其他认证先行解锁语义更精确并收编进统一的LocalAuthExceptionCode枚举。5.2 Face ID 与 stickyAuth 的早期支持0.0.2即支持stickyAuth模式——应用进入后台后保持认证意图这一机制在 3.x 中演化为persistAcrossBackgrounding0.5.3起不再依赖FingerprintCompat直接支持 Face ID 检测0.0.21 就已更新消息以支持 Face ID0.6.0新增sensitiveTransaction参数并升级 Biometric 版本到 beta01同时处理无设备凭据错误——这些参数至今仍是AuthenticationOptions的成员。5.3 本地化与文案定制的演进1.1.11iOS 支持localizedFallbackTitle回退按钮标题本地化1.1.0AndroidAuthMessages中fingerprint*前缀的字段全部重命名为biometric*如fingerprintHint→biometricHint以兼容 Face ID 等多模态生物识别2.0.0起自定义对话框文案统一通过authMessages传入平台特定的AuthMessages子类抽象基类定义于 auth_messages.dart例如同时定制 Android 与 iOSimport package:local_auth_android/local_auth_android.dart; import package:local_auth_darwin/local_auth_darwin.dart; final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, authMessages: const AuthMessages[ AndroidAuthMessages( signInTitle: Oops! Biometric authentication required!, cancelButton: No thanks, ), IOSAuthMessages(cancelButton: No thanks), ], );各平台可定制的字段范围需查阅对应实现包local_auth_android、local_auth_darwin的类定义。5.4 工程化细节的沉淀CHANGELOG 还记录了大量工程实践2.1.7 起发布元数据增加 pub topicsauthentication、biometrics、local-auth1.1.6 从 jcenter 迁移到 mavenCentral0.6.12 起支持 v2 embedding1.1.1 通过升级flutter_plugin_android_lifecycle修复特定版本的 R8 问题1.1.3 修复 iOS 实现的线程问题导致的崩溃。这些历史修复解释了当前工程约束如 Android 侧需要FragmentActivity、依赖flutter_plugin_android_lifecycle的由来。六、升级到 3.x 的迁移实战清单结合前文分析将 2.x 及更早版本升级到 3.x 建议按以下顺序排查错误处理改造将所有on PlatformException分支改为on LocalAuthException并按 第五节错误码表 逐类规划处理策略保留兜底else分支以兼容未来新增错误码参数迁移options: AuthenticationOptions(stickyAuth: ...)改为顶层参数persistAcrossBackgrounding: ...移除useErrorDialogs将原依赖原生对话框的失败分支改写为基于错误码的 UI 处理依赖与导入若直接使用local_auth_ios迁移至local_auth_darwin2.2.0 起Android/iOS 文案定制分别依赖local_auth_android、local_auth_darwin平台配置核验Android 确认FragmentActivity、USE_BIOMETRIC权限、AppCompat 主题三项齐备确认部署设备满足 Android SDK 24 / iOS 13.0 / macOS 10.15 / Windows 10SDK 约束确认 Flutter ≥ 3.38 / Dart ≥ 3.103.0.2若暂不能升级可继续停留在旧版local_auth旧版 Flutter 会自动解析兼容版本实现包3.0.1 已明确此行为回归验证覆盖canCheckBiometrics/isDeviceSupported/getAvailableBiometrics三种能力探测、biometricOnly强制生物认证、persistAcrossBackgrounding后台恢复、以及temporaryLockout/biometricLockout等锁定分支。结语local_auth的 CHANGELOG 本质上是一部 Flutter 平台插件工程化的演进史从单体插件走向联邦架构从字符串错误码走向类型化异常从平台耦合的参数走向扁平、结构化的 API。理解 2.0.0 与 3.0.0 两次破坏性变更的设计意图以及LocalAuthExceptionCode全量错误码的业务语义是平稳升级与构建健壮认证体验的关键。上述所有论断均可对照 CHANGELOG.md、核心实现、异常定义 与 单元测试 逐一印证。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考