local_auth_android 演进全解析从 1.0.0 到 1.0.18 的 Android 本地生物认证插件变迁【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins导读local_auth_android是 Flutter 官方维护的local_auth插件的 Android 端实现位于 packages/local_auth/local_auth_android 目录。本文以其 CHANGELOG.md 为主线结合插件源码、Android 清单文件与单元测试梳理该插件从联邦架构迁移到 1.0.18 版本之间的关键演进包括指纹 API 的现代化改造、设备凭据PIN/图案/密码认证的兼容性修复、依赖与构建工具链的升级节奏以及getEnrolledBiometrics等核心方法的行为修正。读完本文你将理解该插件每个版本背后的设计动机、当前实现的技术骨架以及如何在自己的 Flutter 应用中正确使用这些能力。一、项目定位联邦插件架构中的 Android 实现local_auth_android是一个被 endorsed 的联邦插件实现这意味着应用开发者只需要在pubspec.yaml中正常依赖local_auth这个包就会自动被引入无需手动添加。其 pubspec.yaml 通过如下声明完成注册flutter: plugin: implements: local_auth platforms: android: package: io.flutter.plugins.localauth pluginClass: LocalAuthPlugin dartPluginClass: LocalAuthAndroidDart 侧入口是 lib/local_auth_android.dart 中的LocalAuthAndroid类它继承自LocalAuthPlatform通过名为plugins.flutter.io/local_auth_android的MethodChannel与 Android 原生侧通信原生侧 LocalAuthPlugin.java 实现了MethodCallHandler、FlutterPlugin与ActivityAware三个接口负责承载五个方法调用authenticate、getEnrolledBiometrics、isDeviceSupported、stopAuthentication与deviceSupportsBiometrics。二、版本 1.0.0联邦架构迁移的起点1.0.0 是local_auth_android作为独立包的首个发布版本CHANGELOG 明确指出其性质Initial release from migration to federated architecture.在联邦架构之前Android 实现与 API 定义混在同一个local_auth包内。迁移后API 面authenticate、getEnrolledBiometrics等抽象沉淀到local_auth_platform_interface平台能力由各端独立包提供。这一拆分让 Android 端可以独立迭代、独立发版后续所有版本号变更都聚焦于 Android 平台自身的问题修复与依赖升级。三、1.0.2生物识别枚举与能力检测的行为修正1.0.2 是本插件历史上最重要的行为修复版本CHANGELOG 记录了三点getEnrolledBiometrics不再返回未注册未录入的生物识别类型与文档化行为保持一致getEnrolledBiometrics现在只返回weak和strong两种生物识别类型deviceSupportsBiometrics现在无论注册状态如何都返回正确值。这三条修复在当前源码中均有对应实现。原生侧 LocalAuthPlugin.java 的getEnrolledBiometrics()通过BiometricManager.canAuthenticate()分别探测BIOMETRIC_WEAK与BIOMETRIC_STRONG只有返回BIOMETRIC_SUCCESS即已注册且可用才加入结果列表而hasBiometricHardware()对应deviceSupportsBiometrics则只判断硬件是否缺失BIOMETRIC_ERROR_NO_HARDWARE与注册状态无关。Dart 侧 local_auth_android.dart 将原生返回的字符串列表映射为BiometricType.weak/BiometricType.strong枚举weak对应设备上可用的软硬件生物识别组合strong对应强认证如指纹、虹膜、面部等更安全的认证方式。四、1.0.8告别FingerprintManager全面拥抱androidx.biometric1.0.8 是一次彻底的 API 现代化Removes usages ofFingerprintManagerand otherBiometricManagerdeprecated method usages.早期的 Android 指纹认证基于android.hardware.fingerprint.FingerprintManager它只能处理指纹且在高版本系统上已被标记废弃。1.0.8 之后插件完全转向androidx.biometric的BiometricManager与BiometricPrompt。从当前源码可以看到AndroidManifest.xml 中仅声明android.permission.USE_BIOMETRICAPI 28 的新权限旧的USE_FINGERPRINT权限已不存在LocalAuthPlugin.java 中的硬件能力判断、已注册生物识别枚举全部基于BiometricManager.canAuthenticate(...)实际弹出认证对话框的工作由 AuthenticationHelper.java 中的BiometricPrompt承担。BiometricPrompt的价值在于它原生支持设备凭据PIN/图案/密码 生物识别的混合认证模式这正是 1.0.14 版本修复问题的技术基础。五、1.0.14修复 API RAndroid 11 之前的设备凭据认证1.0.14 修复了一个兼容性关键点Fixes device credential authentication for API versions before R.问题根源在于BiometricManager.canAuthenticate(DEVICE_CREDENTIAL)只在 API 30Android 11R及以上才可靠。当前源码 LocalAuthPlugin.java 对此做了分版本处理public boolean canAuthenticateWithDeviceCredential() { if (Build.VERSION.SDK_INT 30) { // Checking for device credential only authentication via the BiometricManager // is not allowed before API level 30, so we check for presence of PIN, pattern, // or password instead. return isDeviceSecure(); } ... }即API 30 以下通过KeyguardManager.isDeviceSecure()检查锁屏凭据是否存在API 30 及以上才走BiometricManager的DEVICE_CREDENTIAL探测。结合 AuthenticationHelper.java 可以看到认证时允许的认证器默认组合是BIOMETRIC_WEAK | BIOMETRIC_STRONG只有当设备凭据可用且未设置biometricOnly时才会追加DEVICE_CREDENTIAL反之如果只允许生物识别则必须设置负向按钮文本取消按钮。这一设计让插件在低版本设备上也能正确执行指纹失败后回退到 PIN/密码的典型流程而不会因系统 API 限制误判设备不支持凭据认证。六、依赖与构建工具链的持续升级节奏CHANGELOG 中占比最大的内容是依赖版本升级它们是插件保持 Android 生态兼容性的关键。汇总如下版本变更内容影响1.0.6androidx.core 升至 1.8.0基础核心库能力1.0.7Gradle 升至 7.2.1构建工具链1.0.9 / 1.0.12 / 1.0.15 / 1.0.16androidx.fragment 依次升至 1.5.1 / 1.5.2 / 1.5.4 / 1.5.5FragmentActivity生命周期支持1.0.18androidx.core 升至 1.9.0compile SDK 升至 33最低 Flutter 3.0对齐 Android 13API 33编译目标androidx.fragment的升级与AuthenticationHelper直接相关该类同时实现了Application.ActivityLifecycleCallbacks与DefaultLifecycleObserver通过监听 Activity 的暂停/恢复来处理 stickyAuth粘性认证场景——当 Activity 因系统弹窗等原因暂停时如果启用了 stickyAuth插件会忽略用户取消错误并在恢复时重新弹出认证框见 AuthenticationHelper.java。因此 fragment 库的稳定直接决定了认证流程在配置变更旋转屏幕等下的健壮性。七、工程规范与生态兼容性1.0.1 ~ 1.0.17除了功能修复CHANGELOG 还记录了持续的工程质量改进1.0.1采用Object.hash实现hashCode对应 auth_messages_android.dart 中对 10 个消息字段的聚合哈希1.0.3 / 1.0.4 / 1.0.11清理无用 import修复library_private_types_in_public_api、sort_child_properties_last、use_key_in_widget_constructors、avoid_redundant_argument_values等 lint 告警并适配新的 analysis options1.0.5将文档中废弃的 master 分支引用改为 main1.0.10修正local_auth_platform_interface依赖约束到正确的最低版本当前为^1.0.11.0.13改用prefer_relative_imports的相对导入风格1.0.17增加对intl0.18.0 的兼容当前约束为0.17.0 0.19.0。其中intl的兼容与AndroidAuthMessages的默认文案体系有关。auth_messages_android.dart 使用Intl.message定义了 10 条可本地化的默认字符串涵盖Verify identitybiometricHint、Not recognized. Try again.、Success、Cancel、Biometric required、Device credentials required 等提示同时为每条消息标注了最大长度约束按钮类 30 字符、提示类 60 字符Android 官方BiometricPrompt对超长文本会直接抛异常因此自定义AndroidAuthMessages时务必遵守这些限制。八、当前版本1.0.18的完整能力盘点结合源码当前版本的local_auth_android具备以下可验证能力1. 五种平台方法Dart 侧暴露authenticate({localizedReason, authMessages, options})发起认证options支持useErrorDialogs、stickyAuth、sensitiveTransaction对应setConfirmationRequired、biometricOnly四个开关deviceSupportsBiometrics()检测生物识别硬件是否存在getEnrolledBiometrics()返回已注册的weak/strong生物识别类型isDeviceSupported()设备是否处于安全状态有锁屏凭据或有可用生物识别stopAuthentication()取消进行中的认证。2. 认证流程的状态机与错误码LocalAuthPlugin.java 使用AtomicBoolean authInProgress防止并发认证AuthenticationHelper.java 将BiometricPrompt错误码映射为稳定的业务错误码错误码触发条件NotAvailable无设备凭据、硬件不可用/不存在NotEnrolled设备上未录入生物识别LockedOut连续失败 5 次锁定 30 秒PermanentlyLockedOut多次触发 LockedOut需用强认证解锁auth_in_progress/no_activity/no_fragment_activity调用侧前置校验失败3. 测试保障单元测试 LocalAuthTest.java 覆盖了认证中重复调用报错、无前台 Activity 报错、非FragmentActivity报错、biometricOnly时不允许凭据等关键路径集成测试 local_auth_test.dart 在真实设备上验证getEnrolledBiometrics()的可用性。九、升级与使用建议在应用中升级到local_auth_android1.0.18 时需要注意其环境约束pubspec.yamlFlutter3.0.0Dart SDK2.14.0 3.0.0。结合 CHANGELOG 的演进脉络可归纳出以下实践要点宿主 Activity 必须继承FragmentActivity如 Flutter 默认的FlutterFragmentActivity否则authenticate会返回no_fragment_activity错误依赖 AndroidX 而非旧指纹 API项目本身已声明USE_BIOMETRIC权限宿主应用应确保使用 AndroidX 的 activity/fragment且 compile SDK 不低于 33善用错误码做降级捕获PermanentlyLockedOut、LockedOut后引导用户使用 PIN/图案/密码捕获NotEnrolled后引导用户前往系统设置录入生物识别插件内置了去设置对话框stickyAuth 适用于支付类场景开启后应用退到后台再恢复认证框会自动重新弹出无需用户重复操作。从 1.0.0 到 1.0.18local_auth_android的演进轨迹清晰反映了 Flutter 官方插件对 Android 生态的持续跟随从联邦架构拆分到全面 AndroidX 化再到 API R 设备凭据兼容修复与 Android 13 编译目标对齐。这份 CHANGELOG 不仅是版本记录更是一份可复用的 Android 生物认证插件维护实践手册。【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考