Flutter使用local_auth 1.1.4实现生物识别认证时抛出‘未启用必要安全特性’错误

注：该错误在1.1.4版本中属于通用触发错误，插件源码中“无指纹传感器”的注释和实际触发场景完全不匹配，实际多数同类报错都和硬件是否支持指纹无关。

优先排查项（按触发概率从高到低） #

• 权限配置校验
  这个版本的canCheckBiometrics和getAvailableBiometrics接口完全不校验应用实际是否拿到了生物识别权限，只有真正调用认证流程时才会触发权限检查，权限缺失会直接抛该报错。迭代开发时因为Manifest合并规则变化，很容易丢失以下两个必填权限：
  • 必须在AndroidManifest.xml中声明<uses-permission android:name="android.permission.USE_BIOMETRIC" />
  • 兼容Android 9（API 28）及以下设备，必须额外声明<uses-permission android:name="android.permission.USE_FINGERPRINT" />
• MainActivity继承的包名校验
  虽然已经把MainActivity调整为继承FragmentActivity，但必须确认导入的是androidx.fragment.app.FragmentActivity，而非旧的support库版本。包名导错会导致BiometricPrompt无法绑定宿主Activity，直接判定安全特性不可用。
• 主题配置校验
  1.1.4版本的BiometricPrompt强依赖基于Theme.AppCompat或Theme.MaterialComponents的Activity主题，不能使用纯系统主题（如@android:style/Theme.Material.NoActionBar）。如果迭代时修改了MainActivity的启动主题、或者调整了启动页的主题跳转逻辑，导致MainActivity使用了无AppCompat依赖的主题，会直接触发该报错。
• 版本自带bug规避
  该版本开启biometricOnly: true时存在已知逻辑缺陷：只要设备录过指纹，前置检测就会返回通过，但如果设备重启后未输入过一次锁屏密码、生物识别模块处于系统级锁死状态，调用认证时就会直接抛错。临时验证方式是将biometricOnly临时设为false，如果认证流程可以正常拉起，即可确认是该版本的源码bug。
  对应的修复方案是在调用authenticate之前，额外调用auth.isDeviceSupported()做二次校验，这个接口的检测维度会覆盖系统生物识别模块的实际可用状态，比原来的前置检测更严格。
• Manifest合并冲突排查
  如果迭代过程中引入了新的第三方SDK，可能会因为Manifest优先级覆盖，将原有生物识别相关的权限声明挤掉。可以在模块的build.gradle中强制锁定权限声明，避免被其他依赖覆盖：

  android {
      // 保留原有其他配置
      defaultConfig {
          // 保留原有其他配置
          manifestPlaceholders = [
              'USE_BIOMETRIC': 'android.permission.USE_BIOMETRIC',
              'USE_FINGERPRINT': 'android.permission.USE_FINGERPRINT'
          ]
      }
  }
  

内容的提问来源于stack exchange，提问作者Kevin Walter