经典蓝牙#

经典蓝牙更适合持续连接、数据量更大、实时性要求更高的场景，比如：

• 蓝牙耳机音频传输
• 车载设备
• 键盘鼠标
• 打印机

BLE#

BLE 更适合低功耗、小数据量、间歇性通信的场景，比如：

• 智能手环
• 健康设备
• 环境传感器
• 智能门锁
• Beacon 广播设备

如果一句话概括：

• 经典蓝牙偏“持续稳定的数据通道”
• BLE 偏“低功耗设备之间的轻量通信”

所以当我们在 Android 业务开发里说“蓝牙开发”时，很多时候其实默认指的是 BLE 开发。

Central 和 Peripheral#

这是连接层面的角色。

• Central：主动扫描附近设备，并发起连接
• Peripheral：负责广播自己，等待别人连接

在常见业务里：

• 手机通常扮演 Central
• 手环、传感器、硬件模块通常扮演 Peripheral

GATT Client 和 GATT Server#

这是通信层面的角色。

• GATT Client：发起数据请求
• GATT Server：提供服务和数据

在大多数 BLE 场景里：

• Android 手机是 Central
• 同时也是 GATT Client
• 外部 BLE 设备是 Peripheral
• 同时也是 GATT Server

Service、Characteristic、Descriptor#

这是 BLE 数据组织的核心。

• Service：一组相关功能的集合
• Characteristic：真正承载数据的特征值
• Descriptor：对特征值的补充描述

可以把它理解成下面这种层级：

Device
└── Service
    ├── Characteristic
    │   └── Descriptor
    └── Characteristic

Android 官方文档提到，GATT 是 BLE 链路上传输 attribute 的通用规范，而当前 BLE 应用几乎都建立在 GATT 之上。这也是为什么 Android BLE 开发会不断围绕 BluetoothGatt、Service、Characteristic 这些对象展开。
参考：https://developer.android.com/develop/connectivity/bluetooth/ble/ble-overview

Android 12 及以上#

从 Android 12 开始，蓝牙权限拆得更细。Android Developers 文档给出的规则是：

• 扫描设备需要 BLUETOOTH_SCAN
• 让设备可被发现需要 BLUETOOTH_ADVERTISE
• 与已配对设备通信需要 BLUETOOTH_CONNECT

而且这些权限都是运行时权限，需要在代码里动态申请。
参考：https://developer.android.com/develop/connectivity/bluetooth/bt-permissions

Manifest 可以这样写：

<uses-permission
    android:name="android.permission.BLUETOOTH"
    android:maxSdkVersion="30" />

<uses-permission
    android:name="android.permission.BLUETOOTH_ADMIN"
    android:maxSdkVersion="30" />

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

如果你的业务需要让本机对外广播，再补：

<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

Android 11 及以下#

Android 官方文档说明，在 Android 11 及以下，如果应用要执行蓝牙扫描，通常还需要位置权限，因为扫描结果可能被用于推导用户物理位置。
参考：https://developer.android.com/develop/connectivity/bluetooth/bt-permissions

这也是很多开发同学的困惑来源：

• “我明明是在做蓝牙，为啥要定位权限？”

答案是：因为系统从隐私角度把蓝牙扫描和位置推断绑定考虑了。

neverForLocation#

如果你的应用确实不会通过蓝牙扫描结果推导用户位置，Android 官方提供了 neverForLocation 的声明方式，但文档也提醒：加上这个标记后，部分 BLE beacon 结果可能会被过滤掉。这不是一个“随手加了更省事”的配置，而是带有功能权衡的声明。
参考：https://developer.android.com/develop/connectivity/bluetooth/bt-permissions

<uses-permission
    android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />

<uses-permission
    android:name="android.permission.ACCESS_FINE_LOCATION"
    android:maxSdkVersion="30" />

动态申请权限#

以 Android 12+ 为例，可以这样申请：

private val bluetoothPermissionLauncher =
    registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { result ->
        val scanGranted = result[Manifest.permission.BLUETOOTH_SCAN] == true
        val connectGranted = result[Manifest.permission.BLUETOOTH_CONNECT] == true
        if (scanGranted && connectGranted) {
            startBleScan()
        }
    }

private fun requestBluetoothPermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        bluetoothPermissionLauncher.launch(
            arrayOf(
                Manifest.permission.BLUETOOTH_SCAN,
                Manifest.permission.BLUETOOTH_CONNECT
            )
        )
    }
}

经验建议

不要把蓝牙权限写成一套“永远通用”的固定模板。应该根据系统版本、业务是否需要扫描、是否需要连接、是否需要广播，拆成最小权限集合。

为什么扫描最好设置超时#

扫描本身是持续动作，如果没有超时控制，可能会带来几个问题：

• 持续耗电
• 页面退出后仍然占资源
• 结果回调重复触发，状态管理变乱

所以更稳妥的做法是：

• 进入页面后开始扫描
• 找到目标设备立即停止扫描
• 超过固定时间自动停止

private val handler = Handler(Looper.getMainLooper())

private fun startBleScanWithTimeout() {
    startBleScan()
    handler.postDelayed({
        stopBleScan()
    }, 10_000L)
}

读取数据#

private fun readCharacteristic(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic
) {
    gatt.readCharacteristic(characteristic)
}

回调里拿结果：

override fun onCharacteristicRead(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic,
    value: ByteArray,
    status: Int
) {
    if (status == BluetoothGatt.GATT_SUCCESS) {
        // 解析 value
    }
}

写入数据#

private fun writeCharacteristic(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic,
    data: ByteArray
) {
    characteristic.value = data
    gatt.writeCharacteristic(characteristic)
}

订阅通知#

在真实项目里，很多设备数据并不是“你去读一次，它就回一次”，而是设备在状态变化时主动推送。这种场景更常见的方式是 notify。

private val cccdUuid =
    UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")

private fun enableNotification(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic
) {
    gatt.setCharacteristicNotification(characteristic, true)

    val descriptor = characteristic.getDescriptor(cccdUuid) ?: return
    descriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
    gatt.writeDescriptor(descriptor)
}

收到通知时的回调：

override fun onCharacteristicChanged(
    gatt: BluetoothGatt,
    characteristic: BluetoothGattCharacteristic,
    value: ByteArray
) {
    // 设备主动上报数据
}

注意

setCharacteristicNotification() 只是本地开关，很多设备还要求你继续写入 CCCD Descriptor，通知才会真正生效。只调用前者而不写 Descriptor，是非常常见的坑。

为什么很多 BLE 操作要串行#

在工程实践里，BLE 常见问题之一就是多个操作并发发起，导致状态错乱或者失败。因此更稳妥的方案通常是：

• 建立一个操作队列
• 一次只执行一个 GATT 操作
• 等当前操作回调完成，再发下一个

这类设计对提高稳定性非常有帮助。

1. 扫描不到设备#

常见原因有：

• 权限没申请全
• 用户没有授予运行时权限
• 蓝牙没开
• 设备本身没有在广播
• 过滤条件写错
• 使用 neverForLocation 后部分 beacon 被过滤

2. 连接成功但发现不到服务#

这通常意味着：

• 连接状态还不稳定就过早发起了发现
• 设备端 GATT 服务没有按预期准备好
• 某些机型存在兼容性问题
• 连接虽然建立了，但实际通信链路没有稳定下来

3. 写入没报错，但设备没有反应#

可以重点检查：

• 写入的 UUID 是否正确
• 数据协议是否正确
• 写入类型是否匹配
• 是否需要先完成某个握手动作
• 是否应该写入另一个 Characteristic

4. 订阅通知后收不到数据#

优先排查：

• 是否只调用了 setCharacteristicNotification()
• 是否真正写入了 CCCD Descriptor
• 设备是否支持 notify / indicate
• 设备是否只有在特定指令后才开始上报

5. 页面退出后，后续再连接异常#

往往是资源没释放干净。比较基本的收尾动作包括：

private fun releaseGatt() {
    bluetoothGatt?.disconnect()
    bluetoothGatt?.close()
    bluetoothGatt = null
}

如果扫描也还在跑，记得同时停止扫描。

6. 不同手机表现不一致#

这是 Android 蓝牙开发里最现实的问题之一。即使代码一样，也可能出现：

• 某些品牌手机扫描稳定，某些不稳定
• 某些系统版本回调顺序表现不同
• 某些厂商 ROM 的蓝牙栈兼容性更差

因此蓝牙能力越重要，越要做真机覆盖测试，而不是只在单一测试机上验证。