React Native BLE Manager 在 Android 14 上的蓝牙权限问题解析

问题背景

在使用 React Native BLE Manager 库进行蓝牙开发时，许多开发者在 Android 14 设备上遇到了权限问题。错误信息明确指出需要 android.permission.BLUETOOTH_SCAN 权限，即使开发者已经在代码中请求了相关权限。

Android 14 蓝牙权限变更

从 Android 12 (API 31) 开始，Google 引入了更细粒度的蓝牙权限控制，将原来的蓝牙权限拆分为三个独立权限：

1. BLUETOOTH_SCAN - 用于发现和扫描附近的蓝牙设备
2. BLUETOOTH_CONNECT - 用于连接蓝牙设备
3. BLUETOOTH_ADVERTISE - 用于广播设备

这些变更旨在提高用户隐私保护，让应用只能请求它们真正需要的权限。

常见错误实现

许多开发者会犯以下错误：

const result = await PermissionsAndroid.requestMultiple([
  PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
  PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
])
return !!result

这种实现方式存在严重问题，因为 requestMultiple 返回的是一个对象，包含了每个权限的授权状态，直接转换为布尔值会导致权限检查失效。

正确的权限处理方案

1. AndroidManifest.xml 配置

确保在 AndroidManifest.xml 中声明了所有必要的权限：

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28"/>

2. 运行时权限请求

实现一个健壮的权限检查函数：

export const checkBluetoothPermissions = async () => {
  if (Platform.OS === 'ios') {
    return true;
  }

  if (Platform.OS === 'android') {
    if (Platform.Version >= 31) {
      const results = await PermissionsAndroid.requestMultiple([
        PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
        PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
      ]);
      
      return (
        results[PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN] === 
          PermissionsAndroid.RESULTS.GRANTED &&
        results[PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT] === 
          PermissionsAndroid.RESULTS.GRANTED
      );
    } else if (Platform.Version >= 23) {
      const result = await PermissionsAndroid.check(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
      );
      
      if (result) return true;
      
      const granted = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
      );
      return granted === PermissionsAndroid.RESULTS.GRANTED;
    }
    return true; // 对于API 23以下的设备
  }
};

3. 完整的蓝牙扫描流程

const startBluetoothScan = async () => {
  try {
    // 1. 检查并请求权限
    const hasPermission = await checkBluetoothPermissions();
    if (!hasPermission) {
      throw new Error('蓝牙权限被拒绝');
    }

    // 2. 检查蓝牙是否开启
    const isEnabled = await RNBluetoothClassic.isBluetoothEnabled();
    if (!isEnabled) {
      const userEnabled = await RNBluetoothClassic.requestBluetoothEnabled();
      if (!userEnabled) {
        throw new Error('用户拒绝开启蓝牙');
      }
    }

    // 3. 检查位置服务（Android 10及以下需要）
    if (Platform.OS === 'android' && Platform.Version < 31) {
      await checkLocationServices();
    }

    // 4. 开始扫描
    await BleManager.scan([], SCAN_DURATION, ALLOW_DUPLICATES, {
      matchMode: BleScanMatchMode.Sticky,
      scanMode: BleScanMode.LowLatency,
      callbackType: BleScanCallbackType.AllMatches,
    });

  } catch (error) {
    console.error('蓝牙扫描失败:', error);
    // 处理错误
  }
};

兼容性考虑

对于不同 Android 版本，需要采取不同的权限策略：

1. Android 12 (API 31) 及以上：

   • 需要 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 权限
   • 不再需要位置权限来扫描蓝牙设备

2. Android 10 (API 29) 到 Android 11 (API 30)：

   • 需要 ACCESS_FINE_LOCATION 权限
   • 需要位置服务开启

3. Android 9 (API 28) 及以下：

   • 需要 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION 权限

最佳实践建议

1. 权限请求时机：在用户明确需要蓝牙功能时再请求权限，而不是应用启动时就请求。

2. 权限拒绝处理：当用户拒绝权限时，应该优雅地解释为什么需要这些权限，并提供重新请求的选项。

3. 权限检查：在执行任何蓝牙操作前都检查权限状态，因为用户可能随时在系统设置中撤销权限。

4. 错误处理：为各种可能的错误情况（权限拒绝、蓝牙关闭、位置服务关闭等）提供明确的用户反馈和恢复路径。

5. 测试策略：在不同 Android 版本和设备上全面测试蓝牙功能，确保兼容性。

通过遵循这些指导原则，开发者可以构建出在 Android 14 及以上版本中稳定运行的蓝牙应用，同时提供良好的用户体验。