29、指纹认证与跨平台框架：Flutter集成指纹、React Native集成指纹、原生模块封装

跨平台开发现在太普遍了。我这些年做过不少Flutter和React Native的项目，每次遇到指纹认证，团队里总会有人问：「这东西到底能不能跨平台统一处理？」

说实话，指纹认证这种涉及系统底层安全API的功能，不可能完全用Dart或JS搞定。你想想看，Android的指纹API和iOS的LocalAuthentication框架，底层实现天差地别。跨平台框架能做的，就是给你搭一座桥——让你用一套代码调用两边的原生能力。

今天我就把Flutter和React Native两边的集成方案都捋一遍。最后再聊聊怎么封装自己的原生模块，毕竟有些场景下，现成的插件不一定能满足你。

29.1 Flutter集成指纹认证

Flutter这边，官方推荐的插件是 local_auth。这个插件封装了Android和iOS两端的生物识别能力。我最早用的时候它还只支持指纹，现在人脸、虹膜都支持了。

29.1.1 添加依赖与配置

先在 pubspec.yaml 里加上：

dependencies:
  flutter:
    sdk: flutter
  local_auth: ^2.1.0  # 建议用最新稳定版

Android端不需要额外配置，因为插件会自动依赖 androidx.biometric。但iOS端需要在 Info.plist 里加一段描述：

<key>NSFaceIDUsageDescription</key>
<string>我们需要使用Face ID来验证您的身份</string>

嗯，这里要注意——如果你只写「指纹」，用户用Face ID的设备就会崩溃。我遇到过这种线上事故，后来统一改成「生物识别验证」了。

29.1.2 核心调用代码

Flutter里调用指纹认证，核心就三步：检查可用性、弹出认证、处理结果。看代码：

import 'package:local_auth/local_auth.dart';

class BiometricAuthService {
  final LocalAuthentication _auth = LocalAuthentication();

  // 第一步：检查设备是否支持生物识别
  Future<bool> canAuthenticate() async {
    final isAvailable = await _auth.canCheckBiometrics;
    final isDeviceSupported = await _auth.isDeviceSupported();
    return isAvailable && isDeviceSupported;
  }

  // 第二步：执行认证
  Future<bool> authenticate() async {
    try {
      final authenticated = await _auth.authenticate(
        localizedReason: '请验证指纹以登录',
        options: AuthenticationOptions(
          biometricOnly: true,  // 只使用生物识别，不用设备密码
          stickyAuth: true,     // App切到后台再回来，不自动取消
        ),
      );
      return authenticated;
    } on PlatformException catch (e) {
      // 处理各种异常情况
      print('认证失败: ${e.message}');
      return false;
    }
  }
}

这里有个坑——stickyAuth 这个参数。我早期没设这个，用户按Home键再切回来，认证对话框就消失了，体验很差。设成 true 之后，对话框会保持住。

29.1.3 错误处理与状态管理

实际项目中，你不能只返回true/false。用户可能取消、可能失败、可能设备不支持。我习惯封装一个枚举：

enum BiometricResult {
  success,
  failed,
  canceled,
  notAvailable,
  lockedOut,  // 多次失败后被锁定
}

Future<BiometricResult> authenticateWithResult() async {
  if (!await canAuthenticate()) {
    return BiometricResult.notAvailable;
  }
  
  try {
    final result = await _auth.authenticate(
      localizedReason: '请验证指纹',
      options: AuthenticationOptions(biometricOnly: true),
    );
    return result ? BiometricResult.success : BiometricResult.failed;
  } on PlatformException catch (e) {
    if (e.code == 'LockedOut' || e.code == 'PermanentlyLockedOut') {
      return BiometricResult.lockedOut;
    }
    return BiometricResult.canceled;
  }
}

29.2 React Native集成指纹认证

React Native这边，我用得最多的是 react-native-biometrics 这个库。它比Flutter的插件稍微复杂一点，但灵活性更高。

29.2.1 安装与原生配置

npm install react-native-biometrics
# 或者
yarn add react-native-biometrics

Android端，React Native会自动链接。但iOS端需要手动做一步：在Xcode中打开项目，在 Capabilities 里开启 Face ID 权限。

我记得有个同事忘了这一步，结果在iPhone X上测试，一直报「生物识别不可用」。排查了半天才发现是权限没开。

29.2.2 核心调用代码

React Native的调用方式跟Flutter类似，但它是基于Promise的：

import ReactNativeBiometrics from 'react-native-biometrics';

const rnBiometrics = new ReactNativeBiometrics();

// 检查可用性
const checkBiometrics = async () => {
  const { available, biometryType } = await rnBiometrics.isSensorAvailable();
  
  if (available) {
    console.log(`支持的生物识别类型: ${biometryType}`);
    // biometryType 可能是 'Biometrics', 'TouchID', 'FaceID', 'Fingerprint'
  } else {
    console.log('设备不支持生物识别');
  }
};

// 执行指纹认证
const authenticateFingerprint = async () => {
  try {
    const { success } = await rnBiometrics.simplePrompt({
      promptMessage: '请验证指纹',
      cancelButtonText: '取消',
    });
    
    if (success) {
      console.log('认证成功');
      return true;
    } else {
      console.log('用户取消了认证');
      return false;
    }
  } catch (e) {
    console.error('认证出错:', e);
    return false;
  }
};

29.2.3 生成密钥对与签名验证

React Native的 react-native-biometrics 有一个Flutter没有的特性——它支持在安全硬件中生成密钥对，然后用私钥签名数据。这在金融类App里特别有用。

// 创建密钥对
const createKeys = async () => {
  const { publicKey } = await rnBiometrics.createKeys();
  // 把 publicKey 传给后端保存
  return publicKey;
};

// 用私钥签名
const signData = async (data) => {
  const { success, signature } = await rnBiometrics.createSignature({
    promptMessage: '请验证指纹以签名',
    payload: data,
  });
  
  if (success) {
    // 把 signature 传给后端验证
    return signature;
  }
  return null;
};

这个机制说白了就是：指纹验证通过后，系统用私钥对一段数据签名。后端拿着你之前上传的公钥去验签。这样既验证了身份，又保证了数据完整性。

29.3 原生模块封装：打造自己的指纹SDK

有时候第三方插件满足不了你的需求。比如你需要自定义UI、或者要跟已有的安全体系对接。这时候就得自己封装原生模块了。

封装的核心思路是：在原生侧实现指纹认证逻辑，通过平台通道暴露给跨层框架。下面我以Android原生模块为例，讲一下封装要点。

29.3.1 Android原生模块实现

先写一个Java/Kotlin类，封装指纹认证逻辑：

// FingerprintModule.kt
class FingerprintModule(private val context: Context) {
    
    private val executor = ContextCompat.getMainExecutor(context)
    private var biometricPrompt: BiometricPrompt? = null
    
    fun authenticate(
        title: String,
        subtitle: String,
        onSuccess: () -> Unit,
        onError: (String) -> Unit,
        onCancel: () -> Unit
    ) {
        val biometricManager = BiometricManager.from(context)
        when (biometricManager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_STRONG)) {
            BiometricManager.BIOMETRIC_SUCCESS -> {
                // 可以认证
                startBiometricPrompt(title, subtitle, onSuccess, onError, onCancel)
            }
            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> {
                onError("设备没有指纹硬件")
            }
            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> {
                onError("用户没有录入指纹")
            }
            else -> {
                onError("生物识别不可用")
            }
        }
    }
    
    private fun startBiometricPrompt(
        title: String,
        subtitle: String,
        onSuccess: () -> Unit,
        onError: (String) -> Unit,
        onCancel: () -> Unit
    ) {
        val promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle(title)
            .setSubtitle(subtitle)
            .setNegativeButtonText("取消")
            .build()
            
        biometricPrompt = BiometricPrompt(
            context as FragmentActivity,
            executor,
            object : BiometricPrompt.AuthenticationCallback() {
                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                    onSuccess()
                }
                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                    onError(errString.toString())
                }
                override fun onAuthenticationFailed() {
                    onError("指纹不匹配")
                }
            }
        )
        biometricPrompt?.authenticate(promptInfo)
    }
}

29.3.2 平台通道对接（以Flutter为例）

在Flutter插件中，通过MethodChannel把上面的原生模块暴露出去：

// Flutter端
class NativeFingerprint {
  static const _channel = MethodChannel('com.example.fingerprint/auth');
  
  static Future<Map<String, dynamic>> authenticate({
    required String title,
    String subtitle = '',
  }) async {
    try {
      final result = await _channel.invokeMethod('authenticate', {
        'title': title,
        'subtitle': subtitle,
      });
      return Map<String, dynamic>.from(result);
    } on PlatformException catch (e) {
      return {'success': false, 'error': e.message};
    }
  }
}

// 使用
final result = await NativeFingerprint.authenticate(
  title: '验证身份',
  subtitle: '请按指纹',
);
if (result['success'] == true) {
  print('认证成功');
} else {
  print('认证失败: ${result['error']}');
}

29.3.3 封装时的几个关键设计

我封装过好几个版本的指纹SDK，踩了不少坑。总结几个设计要点：

• 异步回调统一：原生侧的回调是异步的，跨平台通道必须用Future/Promise包装好。不要搞成EventChannel那种流式监听，太复杂了。
• 错误码标准化：把Android的 BIOMETRIC_ERROR_* 和iOS的 LAError.* 映射成统一的错误码。前端只需要判断几个固定的code就行。
• 生命周期管理：指纹认证对话框是系统级的，但Activity/Fragment销毁时一定要取消认证。我见过因为没取消导致的内存泄漏。
• 线程安全：原生模块可能被多个线程同时调用，建议加锁或者用队列串行化。

29.4 跨平台指纹认证的架构图

下面这张图展示了Flutter和React Native集成指纹认证的整体架构。你可以看到，不管上层用什么框架，最终都落到Android的BiometricPrompt或iOS的LocalAuthentication上。

从这张图可以看得很清楚：跨平台框架只是「翻译官」，真正的指纹认证工作全在原生层完成。所以你在做跨平台开发时，不要指望一套代码能解决所有问题——Android和iOS的差异，最终还是要通过原生代码来处理。

---

好了，关于指纹认证在跨平台框架中的集成，我就讲这么多。Flutter和React Native的方案各有千秋，选哪个取决于你的团队技术栈。如果你需要高度定制，那就自己封装原生模块——虽然工作量大了点，但可控性最强。

最后说一句：不管用什么框架，安全底线不能丢。指纹数据永远不要传到业务层，更不要传到服务器。验证结果可以传，但原始生物特征数据必须留在安全硬件里。这是原则问题。