Flutter local_auth 插件实战指南本地生物识别认证集成与平台适配【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins本指南基于 Flutter 官方插件仓库packages/local_auth中的 local_auth 文档 及其各平台实现源码系统讲解如何在 Flutter 应用中接入基于设备本地的身份认证指纹、人脸、PIN/图案/密码等。读完本文你将掌握设备能力检测、已注册生物识别查询、authenticate认证调用、异常处理、iOS/Android 平台配置以及 Sticky Auth 等完整实战方案。插件概述与支持范围local_auth是 Flutter 团队维护的官方插件用于在设备本地完成用户身份认证认证过程不依赖网络服务所有生物识别数据均保存在设备端。在受支持的设备上它支持指纹、人脸等生物识别方式同时也能回退到设备级认证PIN、图案、密码。从 pubspec.yaml 可以看出该插件采用 federated plugin联邦插件架构通过local_auth_platform_interface定义统一接口按平台分发到对应实现包平台支持版本默认实现包AndroidSDK 16注isDeviceSupported()在 SDK 23 / Android 6.0 之前恒为 falselocal_auth_androidiOS9.0同时兼容 Touch ID 与 Face IDlocal_auth_iosWindowsWindows 10local_auth_windows在依赖声明中插件会通过default_package字段自动选择对应平台的实现Dart 侧只需依赖主包local_auth即可无需手动添加平台实现包。基础用法设备能力检测调用authenticate之前通常需要先确认设备是否具备本地认证能力。核心入口类是LocalAuthentication定义于 lib/src/local_auth.dart提供两个能力检测 APIcanCheckBiometrics设备硬件是否支持生物识别检测即使尚未注册任何生物信息也返回 trueisDeviceSupported()设备是否支持某种形式的本地认证生物识别或可回退到设备凭据。推荐组合使用import package:local_auth/local_auth.dart; final LocalAuthentication auth LocalAuthentication(); final bool canAuthenticateWithBiometrics await auth.canCheckBiometrics; final bool canAuthenticate canAuthenticateWithBiometrics || await auth.isDeviceSupported();从平台接口 local_auth_platform_interface.dart 的注释可以确认deviceSupportsBiometrics()即canCheckBiometrics的底层实现即使当前没有注册任何生物识别也会返回 true——因此它只回答硬件在不在不回答有没有录入两者切勿混淆。已注册的生物识别getAvailableBiometrics()用于获取设备上已注册的生物识别类型列表返回类型为ListBiometricType。目前插件定义了以下类型见 biometric_type.dartBiometricType.face人脸认证BiometricType.fingerprint指纹认证BiometricType.iris虹膜接口已定义官方注释标注not yet implemented尚未实现BiometricType.strong平台 API 认定为强生物识别如 Android Class 3BiometricType.weak平台 API 认定为弱生物识别如 Android Class 2。final ListBiometricType availableBiometrics await auth.getAvailableBiometrics(); if (availableBiometrics.isNotEmpty) { // Some biometrics are enrolled. } if (availableBiometrics.contains(BiometricType.strong) || availableBiometrics.contains(BiometricType.face)) { // Specific types of biometrics are available. // Use checks like this with caution! }需要特别注意的是生物识别类型是设备相关且平台相关的未来可能新增其他类型。因此官方建议——只要判断已注册了某种生物识别isNotEmpty即可尽量不要依赖具体类型做分支逻辑。平台差异Android 上的类型映射从 local_auth_android.dart 的getEnrolledBiometrics()实现可以看到Android 端目前只会把平台返回的weak/strong字符串映射为BiometricType.weak/BiometricType.strong并不会返回face或fingerprint这类具体类型。这也解释了 README 中Android 上尽量只做非空判断的深层原因。执行认证authenticate 与 AuthenticationOptionsauthenticate()是插件的核心方法默认行为是优先使用生物识别同时允许回退到 PIN、图案或密码try { final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance); // ··· } on PlatformException { // ... }方法签名见 local_auth.dart要点localizedReason必填向用户展示的认证提示文案不能为空典型写法如Authenticate to access MyApp.authMessages自定义各平台弹窗文案默认提供 iOS / Android / Windows 三套默认消息optionsAuthenticationOptions配置项返回值认证成功返回true否则返回false异常存在技术性问题如缺少硬件时会抛出PlatformException在 iOS 模拟器上可能抛出 code 为otherOperatingSystem的异常。强制生物识别biometricOnly如果业务要求必须通过生物识别不允许回退到 PIN/图案/密码传入biometricOnly: truefinal bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, options: const AuthenticationOptions(biometricOnly: true));注意biometricOnly在 Windows 上不受支持——Windows 实现底层依赖 Windows Hello API该 API 不支持选择认证方式。从 error_codes.dart 可以看到Windows 端会抛出 code 为biometricOnlyNotSupported的PlatformException。跨平台应用务必留意此限制。AuthenticationOptions 全部配置项AuthenticationOptions定义于 auth_options.dart是一个immutable类共四个可选参数均有默认值参数默认值作用useErrorDialogstrue是否由系统处理用户可自行修复的问题如未录入指纹时引导用户去设置页添加不可修复的问题如设备没有生物传感器仍会抛出PlatformExceptionstickyAuthfalse认证过程中应用进入后台时是否在应用恢复后自动继续认证详见下文 Sticky Auth 小节sensitiveTransactiontrue是否启用平台特定的安全预防措施。例如 Android 人脸解锁时人脸识别成功后系统会弹出确认对话框确保用户本意是解锁设备biometricOnlyfalse是否禁止回退到非生物识别方式PIN、密码、图案弹窗体系默认弹窗、错误弹窗与自定义文案默认弹窗场景插件在以下两类场景提供默认弹窗Passcode/PIN/Pattern 未设置用户尚未在 iOS 配置密码、或在 Android 配置 PIN/图案生物识别未注册用户未在设备上注册任何生物识别。当调用authenticate时用户缺少必要的认证方式系统会当场给出去注册或取消认证两个选项。关闭错误弹窗如果不想使用默认弹窗将useErrorDialogs设为false让authenticate在这些场景下立即返回错误由应用自行处理import package:local_auth/error_codes.dart as auth_error; try { final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, options: const AuthenticationOptions(useErrorDialogs: false)); // ··· } on PlatformException catch (e) { if (e.code auth_error.notAvailable) { // Add handling of no hardware here. } else if (e.code auth_error.notEnrolled) { // ... } else { // ... } }自定义弹窗文案AuthMessages不同平台的弹窗文案各不相同需要按平台分别定制因此需要导入对应的平台实现包import package:local_auth_android/local_auth_android.dart; import package:local_auth_ios/local_auth_ios.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, ), ]);AndroidAuthMessages 可定制项根据 auth_messages_android.dart 的源码定义Android 端支持以下字段大多数有 60 字符上限按钮类有 30 字符上限字段含义biometricHint引导用户如何完成生物认证的提示文案≤60 字符biometricNotRecognized认证失败提示≤60 字符biometricRequiredTitle设备未设置生物认证时弹窗标题≤60 字符biometricSuccess认证成功提示≤60 字符cancelButton离开当前弹窗的按钮文案≤30 字符deviceCredentialsRequiredTitle设备未设置凭据认证时弹窗标题≤60 字符deviceCredentialsSetupDescription引导用户去设置设备凭据的说明goToSettingsButton跳转设置页的按钮文案≤30 字符goToSettingsDescription引导用户去设置生物认证的说明signInTitle提示用户扫描生物特征的弹窗标题≤60 字符未指定的字段会使用Intl.message提供的英文默认文案如Verify identity、Success、Cancel、Authentication required、Biometric required、Go to settings等且这些默认文案位于 auth_messages_android.dart 文件底部便于本地化扩展。IOSAuthMessages 可定制项根据 auth_messages_ios.dart 的源码定义iOS 端支持字段含义lockOut提示用户重新启用设备生物识别的文案goToSettingsButton跳转设置页按钮文案≤30 字符goToSettingsDescription引导用户去设置生物识别的说明cancelButton离开当前弹窗的按钮文案≤30 字符localizedFallbackTitle认证弹窗中回退按钮的本地化标题异常与错误码体系authenticate在多种错误场景下抛出PlatformException。所有已知错误码集中在 error_codes.dart建议针对关键错误码做专门处理错误码常量值含义passcodeNotSetPasscodeNotSet用户未设置密码iOS或 PIN/图案/密码AndroidnotEnrolledNotEnrolled用户未注册任何生物识别notAvailableNotAvailable设备没有生物识别硬件otherOperatingSystemOtherOperatingSystem操作系统不受支持如 iOS 模拟器lockedOutLockedOut因尝试次数过多API 暂时锁定permanentlyLockedOutPermanentlyLockedOut比lockedOut更持久的锁定必须用强认证如 PIN/图案/密码解锁biometricOnlyNotSupportedbiometricOnlyNotSupportedbiometricOnly在 Windows 上不受支持典型处理示例import package:flutter/services.dart; import package:local_auth/error_codes.dart as auth_error; import package:local_auth/local_auth.dart; final LocalAuthentication auth LocalAuthentication(); try { final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, options: const AuthenticationOptions(useErrorDialogs: false)); // ··· } on PlatformException catch (e) { if (e.code auth_error.notEnrolled) { // Add handling of no hardware here. } else if (e.code auth_error.lockedOut || e.code auth_error.permanentlyLockedOut) { // ... } else { // ... } }iOS 集成插件同时支持 Touch ID 和 Face ID。若使用 Face ID必须在Info.plist中添加NSFaceIDUsageDescription描述keyNSFaceIDUsageDescription/key stringWhy is my app authenticating using face id?/string缺少该描述时系统会弹出对话框告知用户应用尚未更新以支持 Face ID体验很差。建议在文案中说明应用使用 Face ID 的具体目的以通过 App Store 审核。Android 集成Activity 变更关键步骤local_auth要求宿主 Activity 必须是FragmentActivity而非普通Activity若直接使用FlutterActivity请在AndroidManifest.xml中改为FlutterFragmentActivity若使用自定义 Activity需修改MainActivity.javaimport io.flutter.embedding.android.FlutterFragmentActivity; public class MainActivity extends FlutterFragmentActivity { // ... }或MainActivity.ktimport io.flutter.embedding.android.FlutterFragmentActivity class MainActivity: FlutterFragmentActivity() { // ... }从仓库的 androidTest 目录 FlutterFragmentActivityTest.java 可以印证官方在集成测试中专门验证了FlutterFragmentActivity的继承关系这是插件正常工作的硬性前提。权限声明在AndroidManifest.xml中添加USE_BIOMETRIC权限manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.example.app uses-permission android:nameandroid.permission.USE_BIOMETRIC/ manifestAPI 版本兼容性说明插件可在 SDK 16 上构建和运行但isDeviceSupported()在 SDK 23Android 6.0之前恒返回 false即较早版本无法可靠地通过该 API 判断设备支持性Android 9API 28及更早版本上只能检测指纹硬件是否存在。若要支持其他生物识别类型如人脸且兼容低于 Android Q 的版本不要调用getAvailableBiometrics直接以biometricOnly: true调用authenticate即可——若硬件不可用认证会直接返回错误。LaunchTheme 主题要求为防止 Android 8 及以下系统崩溃LaunchTheme的 parent 必须是合法的Theme.AppCompat主题。在android/app/src/main/res/values/styles.xml中找到名为LaunchTheme的 style 并修改 parentresources style nameLaunchTheme parentTheme.AppCompat.DayNight ... /style ... /resources使用Theme.AppCompat.DayNight还能让生物识别弹窗跟随系统明暗模式。若项目没有styles.xml也可直接在AndroidManifest.xml的activity上指定主题application ... activity ... android:themestyle/Theme.AppCompat.DayNight ... /activity /application从 local_auth_android 实现包自带的 styles.xml 可以看到插件自身的认证对话框scan_fp.xml、go_to_setting.xml等布局位于 drawable 与 layout 目录同样基于 AppCompat 主题体系构建这也是要求宿主主题兼容 AppCompat 的底层原因。Sticky Auth后台恢复后自动续认证当认证过程中应用被系统置入后台例如用户在完成认证前突然接到电话出于安全原因认证流程必须中断。此时行为由stickyAuth决定stickyAuth: false默认应用一进入后台插件立刻向 Dart 侧返回失败结果需要应用自行决定是否重新发起认证stickyAuth: true插件不会立即返回失败而是在应用恢复前台后自动重试认证。final bool didAuthenticate await auth.authenticate( localizedReason: Please authenticate to show account balance, options: const AuthenticationOptions(stickyAuth: true));从 auth_options.dart 的字段注释可以确认这一机制该选项专门应对用户还没来得及认证就收到电话这类场景避免打断用户的认证流程。架构解读联邦插件如何工作从源码结构看local_auth采用标准 federated plugin 分层local_auth面向开发者的主包导出LocalAuthentication类、AuthenticationOptions和BiometricTypelocal_auth_platform_interface定义LocalAuthPlatform抽象接口authenticate、deviceSupportsBiometrics、getEnrolledBiometrics、isDeviceSupported、stopAuthentication并提供基于MethodChannel的默认实现各平台实现通过LocalAuthPlatform.instance注册自己local_auth_androidAndroid 实现通过MethodChannel(plugins.flutter.io/local_auth_android)与原生侧通信底层基于 AndroidX Biometric 库核心原生逻辑位于 LocalAuthPlugin.java 与 AuthenticationHelper.javalocal_auth_iosiOS 实现底层使用系统的 LocalAuthentication 框架LAContext原生逻辑位于 FLTLocalAuthPlugin.mlocal_auth_windowsWindows 实现基于 Windows HelloDart 侧通过 pigeon 生成的消息通道调用定义于 messages.dart。这一架构带来的好处是应用层代码完全平台无关新增平台支持只需新增实现包不会破坏现有 API。完整接入检查清单pubspec.yaml中添加依赖local_auth: ^2.1.4当前仓库版本见 pubspec.yaml调用canCheckBiometrics/isDeviceSupported()判断设备能力可选调用getAvailableBiometrics()查询已注册生物类型注意 Android Q 的兼容建议以合适的localizedReason、authMessages和AuthenticationOptions调用authenticate捕获PlatformException并按 error_codes.dart 中的错误码分流处理iOSInfo.plist添加NSFaceIDUsageDescriptionAndroidActivity 改为继承FlutterFragmentActivity、声明USE_BIOMETRIC权限、将LaunchTheme的 parent 设为Theme.AppCompat主题按业务需要决定是否开启stickyAuth与sensitiveTransaction。示例应用可参考 local_auth/example 目录下的 main.dart 与集成测试 local_auth_test.dart其中完整演示了能力检测、认证调用与错误处理的标准写法。【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考