Flutter BLE开发避坑实录：flutter_blue_plus插件从扫描到数据收发的完整实战

在移动应用开发中，蓝牙低功耗（BLE）技术的应用越来越广泛，从健康监测设备到智能家居控制，BLE为物联网应用提供了便捷的无线通信方案。Flutter作为跨平台开发框架，通过flutter_blue_plus插件为开发者提供了BLE开发能力。然而，在实际开发过程中，从设备扫描到稳定数据传输的每个环节都可能隐藏着各种"坑"，这些坑往往会让开发者耗费大量时间调试。

本文将分享一个完整的Flutter BLE开发实战经验，重点解决那些官方文档没有详细说明，但实际项目中必然会遇到的典型问题。不同于基础教程，我们更关注生产环境中需要的健壮性设计、异常处理和性能优化。无论你是正在开发智能硬件配套应用，还是需要集成第三方BLE设备，这些经验都能帮助你少走弯路。

1. 环境配置与权限处理

BLE开发的第一步是正确配置环境，这一步看似简单，却往往是第一个"坑"。不同平台（Android/iOS）对BLE权限的要求差异很大，而且随着系统版本更新，权限模型也在不断变化。

1.1 Android权限配置

在Android上，BLE权限配置需要特别注意以下几点：

• 基础蓝牙权限：这是使用蓝牙功能的最低要求
• 位置权限：从Android 6.0开始，扫描BLE设备需要位置权限
• 后台权限：如果应用需要在后台使用蓝牙，需要额外声明

xml复制<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<!-- 针对Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" 
    android:usesPermissionFlags="neverForLocation"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

注意：从Android 12开始，Google引入了新的蓝牙权限模型，建议同时声明新旧两套权限以保证兼容性。

1.2 iOS权限配置

iOS的权限配置同样有其特殊性：

xml复制<!-- Info.plist -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限来连接您的设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要蓝牙权限来连接您的设备</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>需要位置权限来扫描蓝牙设备</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要位置权限来扫描蓝牙设备</string>

iOS上的一个常见问题是，即使用户授予了"使用时允许"的权限，当应用进入后台时，蓝牙连接可能会被系统中断。如果需要后台持续使用蓝牙功能，必须在Xcode中启用"Background Modes"中的"Uses Bluetooth LE accessories"选项。

1.3 运行时权限请求

仅仅在配置文件中声明权限是不够的，还需要在运行时动态请求权限。以下是一个跨平台的权限请求封装：

dart复制Future<bool> requestBlePermissions() async {
  if (Platform.isAndroid) {
    // Android 12+需要请求BLUETOOTH_SCAN和BLUETOOTH_CONNECT
    final status = await Permission.bluetoothScan.request();
    if (!status.isGranted) return false;
    
    final connectStatus = await Permission.bluetoothConnect.request();
    if (!connectStatus.isGranted) return false;
    
    // 仍然需要位置权限来获取扫描结果
    final locationStatus = await Permission.locationWhenInUse.request();
    return locationStatus.isGranted;
  } else if (Platform.isIOS) {
    // iOS只需要请求一次蓝牙权限
    final status = await Permission.bluetooth.request();
    return status.isGranted;
  }
  return false;
}

在实际项目中，建议在应用启动时就检查并请求必要权限，而不是等到用户触发蓝牙操作时才处理。这样可以提前发现权限问题，提供更好的用户体验。

2. 设备扫描与过滤策略

设备扫描是BLE交互的第一步，也是性能优化的关键环节。不合理的扫描策略会导致电量快速消耗和设备发现率低的问题。

2.1 基础扫描实现

使用flutter_blue_plus进行设备扫描的基本代码如下：

dart复制final FlutterBluePlus flutterBlue = FlutterBluePlus.instance;

void startScanning() {
  // 先停止可能存在的扫描
  flutterBlue.stopScan();
  
  // 设置扫描参数
  const scanSettings = ScanSettings(
    androidScanMode: AndroidScanMode.lowLatency,
    serviceUuids: [], // 可以指定只扫描特定服务的设备
    allowDuplicates: true, // 是否接收重复的广播包
  );
  
  // 开始扫描
  flutterBlue.startScan(
    timeout: const Duration(seconds: 15),
    settings: scanSettings,
  );
  
  // 监听扫描结果
  flutterBlue.scanResults.listen((results) {
    for (ScanResult result in results) {
      // 处理每个扫描到的设备
      handleScanResult(result);
    }
  });
}

2.2 设备过滤策略

在实际项目中，我们通常只需要连接特定类型的设备，因此需要实现有效的过滤策略。常见的过滤条件包括：

• 设备名称前缀：许多厂商会使用特定前缀标识自己的设备
• 服务UUID：设备广播的服务标识符
• 制造商数据：广播包中的厂商特定数据

dart复制void handleScanResult(ScanResult result) {
  // 基础过滤：设备名称
  if (result.device.name.isEmpty) return;
  
  // 示例：过滤名称以"T"开头的设备
  const targetPrefix = 'T';
  if (!result.device.name.startsWith(targetPrefix)) return;
  
  // 进阶过滤：检查广播数据中的服务UUID
  final serviceUuids = result.advertisementData.serviceUuids;
  if (serviceUuids.isEmpty) return;
  
  // 示例：检查是否包含特定服务UUID
  const requiredService = '0000180f-0000-1000-8000-00805f9b34fb';
  if (!serviceUuids.any((uuid) => uuid.toString() == requiredService)) return;
  
  // 更精细的过滤：检查制造商数据
  final manufacturerData = result.advertisementData.manufacturerData;
  if (manufacturerData != null) {
    // 解析制造商特定数据
    final manufacturerId = manufacturerData.bytes[0] + (manufacturerData.bytes[1] << 8);
    if (manufacturerId != 0xFFFF) return; // 示例：只接受特定厂商ID
    
    // 可以进一步解析制造商数据中的其他信息
  }
  
  // 通过所有过滤条件，处理有效设备
  onDeviceFound(result.device);
}

2.3 扫描性能优化

长时间持续扫描会显著增加设备电量消耗，因此需要优化扫描策略：

1. 间歇扫描：扫描10秒，暂停5秒，循环进行
2. 按需扫描：只在用户主动请求或应用在前台时扫描
3. 低功耗模式：在后台时使用AndroidScanMode.lowPower

dart复制Timer? _scanTimer;
bool _isScanning = false;

void startIntervalScanning() {
  if (_isScanning) return;
  
  _isScanning = true;
  _startScanCycle();
}

void _startScanCycle() {
  // 开始扫描
  flutterBlue.startScan(timeout: const Duration(seconds: 10));
  
  // 10秒后停止扫描
  _scanTimer = Timer(const Duration(seconds: 10), () {
    flutterBlue.stopScan();
    
    // 暂停5秒后重新开始扫描
    _scanTimer = Timer(const Duration(seconds: 5), _startScanCycle);
  });
}

void stopIntervalScanning() {
  _scanTimer?.cancel();
  _scanTimer = null;
  flutterBlue.stopScan();
  _isScanning = false;
}

对于已知设备，可以使用flutterBlue.connectedDevices获取已连接设备列表，避免不必要的扫描。

3. 设备连接与状态管理

设备连接是BLE交互中最不稳定的环节，需要处理各种异常情况和状态变化。一个健壮的连接管理器是BLE应用的核心组件。

3.1 连接参数配置

flutter_blue_plus提供了多种连接参数，合理配置这些参数可以显著提高连接稳定性：

dart复制Future<void> connectToDevice(BluetoothDevice device) async {
  try {
    await device.connect(
      timeout: const Duration(seconds: 15), // 连接超时时间
      autoConnect: false, // 是否自动重连
      mtu: 512, // 请求的MTU大小
      refreshGatt: true, // 是否刷新GATT缓存
    );
    
    // 连接成功后发现服务
    List<BluetoothService> services = await device.discoverServices();
    onConnected(device, services);
  } catch (e) {
    onConnectionFailed(device, e);
  }
}

提示：autoConnect参数在Android和iOS上的行为不同。在Android上，设置为true会让系统自动维护连接，但在iOS上效果有限。

3.2 连接状态监听

BLE连接可能会因为各种原因断开，因此需要持续监听连接状态：

dart复制StreamSubscription<BluetoothConnectionState>? _connectionSubscription;

void monitorConnection(BluetoothDevice device) {
  _connectionSubscription?.cancel();
  
  _connectionSubscription = device.connectionState.listen((state) {
    switch (state) {
      case BluetoothConnectionState.connected:
        onDeviceConnected(device);
        break;
      case BluetoothConnectionState.disconnected:
        onDeviceDisconnected(device);
        break;
      case BluetoothConnectionState.connecting:
        // 连接中状态
        break;
    }
  });
}

在实际项目中，建议将连接状态与UI状态绑定，为用户提供明确的连接状态反馈。

3.3 连接重试机制

由于BLE连接的不稳定性，实现自动重试机制是必要的：

dart复制Future<void> connectWithRetry(
  BluetoothDevice device, {
  int maxRetries = 3,
  Duration retryDelay = const Duration(seconds: 2),
}) async {
  int attempt = 0;
  
  while (attempt < maxRetries) {
    try {
      await device.connect(timeout: const Duration(seconds: 10));
      return; // 连接成功，退出循环
    } catch (e) {
      attempt++;
      if (attempt >= maxRetries) rethrow;
      
      await Future.delayed(retryDelay);
    }
  }
}

对于关键设备，可以实现更复杂的退避策略，如指数退避算法，逐步增加重试间隔。

3.4 多设备连接管理

当应用需要同时管理多个BLE设备时，需要更复杂的状态管理：

dart复制class DeviceManager {
  final Map<String, BluetoothDevice> _connectedDevices = {};
  final Map<String, StreamSubscription> _connectionSubscriptions = {};
  
  Future<void> connectDevice(BluetoothDevice device) async {
    final deviceId = device.remoteId.str;
    
    if (_connectedDevices.containsKey(deviceId)) {
      return; // 已连接，不再重复连接
    }
    
    try {
      await connectWithRetry(device);
      
      // 连接成功后保存设备和状态监听
      _connectedDevices[deviceId] = device;
      _connectionSubscriptions[deviceId] = 
          device.connectionState.listen(_handleConnectionState);
      
      // 发现服务等后续操作
      await _initializeDevice(device);
    } catch (e) {
      _cleanupDevice(device);
      rethrow;
    }
  }
  
  void _handleConnectionState(BluetoothConnectionState state) {
    // 处理连接状态变化
  }
  
  Future<void> disconnectDevice(BluetoothDevice device) async {
    final deviceId = device.remoteId.str;
    await device.disconnect();
    _cleanupDevice(device);
  }
  
  void _cleanupDevice(BluetoothDevice device) {
    final deviceId = device.remoteId.str;
    _connectionSubscriptions[deviceId]?.cancel();
    _connectionSubscriptions.remove(deviceId);
    _connectedDevices.remove(deviceId);
  }
}

这种集中式的设备管理可以避免资源泄漏和状态不一致问题。

4. 数据传输优化与MTU协商

BLE数据传输受限于协议本身的特性，需要进行特殊处理才能实现高效可靠的数据交换。

4.1 MTU协商

MTU（Maximum Transmission Unit）决定了单次数据传输的最大大小。默认MTU通常较小（如23字节），但可以通过协商增大：

dart复制Future<int> negotiateMtu(BluetoothDevice device) async {
  try {
    // 获取当前MTU
    final currentMtu = await device.mtu.first;
    
    // 请求更大的MTU（Android特有，iOS会自动协商）
    if (Platform.isAndroid) {
      const requestedMtu = 512;
      final negotiatedMtu = await device.requestMtu(requestedMtu);
      return negotiatedMtu;
    }
    
    return currentMtu;
  } catch (e) {
    // MTU协商失败，使用默认值
    return 23;
  }
}

注意：实际协商得到的MTU可能小于请求值，取决于设备支持情况。iOS平台会自动协商最佳MTU，不需要手动请求。

4.2 数据分包处理

当发送的数据超过MTU大小时，需要手动分包：

dart复制Future<void> writeLargeData(
  BluetoothCharacteristic characteristic,
  List<int> data, {
  int chunkSize = 512,
}) async {
  final totalLength = data.length;
  int offset = 0;
  
  while (offset < totalLength) {
    final end = min(offset + chunkSize, totalLength);
    final chunk = data.sublist(offset, end);
    
    await characteristic.write(chunk);
    offset = end;
    
    // 可选：添加小延迟避免堵塞
    await Future.delayed(const Duration(milliseconds: 10));
  }
}

接收大数据时同样需要考虑分包情况，需要在应用层实现数据重组逻辑。

4.3 数据收发模式

BLE提供了几种不同的数据收发模式，各有优缺点：

dart复制// 设置通知监听
Future<void> setupNotifications(BluetoothCharacteristic characteristic) async {
  await characteristic.setNotifyValue(true);
  
  characteristic.value.listen((data) {
    if (data != null && data.isNotEmpty) {
      handleIncomingData(data);
    }
  });
}

对于关键数据，建议使用Indicate模式，因为它包含了传输确认机制，比Notify更可靠。

4.4 数据传输性能优化

提高BLE数据传输性能的几个实用技巧：

1. 批量写入：合并多个小数据包为一个较大的包
2. 适当延迟：在连续写入之间添加小延迟（10-50ms）
3. 错误重试：对失败的写入操作实现自动重试
4. 流量控制：根据连接质量动态调整数据发送速率

dart复制class DataSender {
  final BluetoothCharacteristic _characteristic;
  final Queue<List<int>> _dataQueue = Queue();
  bool _isSending = false;
  
  DataSender(this._characteristic);
  
  void enqueueData(List<int> data) {
    _dataQueue.add(data);
    _sendNext();
  }
  
  Future<void> _sendNext() async {
    if (_isSending || _dataQueue.isEmpty) return;
    
    _isSending = true;
    try {
      final data = _dataQueue.removeFirst();
      await _characteristic.write(data);
      
      // 添加小延迟避免堵塞
      await Future.delayed(const Duration(milliseconds: 20));
    } catch (e) {
      // 错误处理
    } finally {
      _isSending = false;
      _sendNext();
    }
  }
}

这种队列化的发送机制可以有效管理数据流，避免堵塞和丢失。

5. 后台运行与连接保活

对于需要长时间连接BLE设备的应用，后台运行和连接保活是必须解决的难题。

5.1 Android后台处理

在Android上，保持后台BLE连接需要注意：

1. 使用前台服务：防止应用被系统杀死
2. 优化扫描策略：在后台使用低功耗扫描模式
3. 处理Doze模式：请求忽略电池优化

dart复制// 在Flutter中启动前台服务
Future<void> startForegroundService() async {
  const methodChannel = MethodChannel('com.example/ble_service');
  try {
    await methodChannel.invokeMethod('startForegroundService');
  } on PlatformException catch (e) {
    // 处理异常
  }
}

对应的Android原生代码需要实现前台服务：

java复制// Android原生代码
public class BleForegroundService extends Service {
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        Notification notification = createNotification();
        startForeground(NOTIFICATION_ID, notification);
        return START_STICKY;
    }
    
    private Notification createNotification() {
        // 创建通知
    }
}

5.2 iOS后台处理

iOS上的后台BLE处理有其特殊性：

1. 配置后台模式：在Info.plist中声明蓝牙后台能力
2. 使用特定的扫描选项：
3. 处理连接事件：实现centralManager:willRestoreState:方法

dart复制// 在iOS上配置后台扫描选项
void startBackgroundScan() {
  if (!Platform.isIOS) return;
  
  flutterBlue.startScan(
    timeout: Duration(seconds: 60),
    settings: ScanSettings(
      androidScanMode: AndroidScanMode.lowPower,
      iosAllowDuplicates: true, // iOS后台需要允许重复
    ),
  );
}

5.3 跨平台连接保活策略

实现可靠的连接保活需要考虑以下方面：

1. 心跳机制：定期发送小数据包保持连接活跃
2. 断开检测：快速发现连接丢失并尝试恢复
3. 状态保存：保存连接状态以便应用重启后恢复

dart复制class ConnectionKeeper {
  final BluetoothDevice _device;
  Timer? _heartbeatTimer;
  StreamSubscription? _connectionSubscription;
  
  ConnectionKeeper(this._device);
  
  void start() {
    // 监听连接状态
    _connectionSubscription = _device.connectionState.listen((state) {
      if (state == BluetoothConnectionState.disconnected) {
        _reconnect();
      }
    });
    
    // 启动心跳
    _heartbeatTimer = Timer.periodic(Duration(seconds: 30), (_) {
      _sendHeartbeat();
    });
  }
  
  Future<void> _sendHeartbeat() async {
    try {
      await _device.readCharacteristic(_heartbeatCharacteristic);
    } catch (e) {
      _reconnect();
    }
  }
  
  Future<void> _reconnect() async {
    await connectWithRetry(_device, maxRetries: 5);
  }
  
  void stop() {
    _heartbeatTimer?.cancel();
    _connectionSubscription?.cancel();
  }
}

5.4 系统策略适配

不同厂商的Android设备可能有不同的后台限制策略，需要进行适配：

1. 自启动管理：引导用户将应用加入自启动白名单
2. 电池优化：引导用户关闭对应用的电池优化
3. 后台弹出界面：部分设备需要允许后台弹出界面

dart复制Future<void> checkBatteryOptimization() async {
  if (!Platform.isAndroid) return;
  
  const channel = MethodChannel('com.example/device_settings');
  final isIgnoringBatteryOptimizations = 
      await channel.invokeMethod('isIgnoringBatteryOptimizations');
  
  if (!isIgnoringBatteryOptimizations) {
    // 引导用户前往设置关闭电池优化
    await channel.invokeMethod('requestIgnoreBatteryOptimizations');
  }
}

这些策略的综合应用可以显著提高BLE连接在后台的稳定性，但需要注意过度保活可能会影响设备电池寿命，需要在用户体验和电量消耗之间找到平衡。