简介一份面向iOS开发者的蓝牙开发学习工程围绕苹果核心蓝牙框架演示低功耗蓝牙设备通信的完整实现。工程以BluetoothDemo-master命名覆盖从初始化中央管理器、扫描发现外围设备、建立连接到获取服务与特征、读写数据及订阅通知等关键环节并对通用属性协议结构及iOS 13以上蓝牙权限处理做了示例适合正在学习蓝牙协议或需要快速搭建低功耗蓝牙功能的中级开发者。压缩包共39个文件包含9个M源码文件、6个头文件、12张界面预览图、三个属性列表与两个故事板文件以及工程配置文件整体仅60KB结构精简便于逐文件分析。已有137人学习浏览这份工程代码注释清晰、目录规整参照示例即可掌握iOS蓝牙开发的核心流程与排错思路是搭建可用低功耗蓝牙应用的实用参考。1. iOS 蓝牙开发为什么给人「难搞」的印象iOS 蓝牙开发最劝退的地方不是 API 复杂而是所有操作都靠异步回调扫描、连接、发现服务、发现特征、读写各走各的 delegate代码一多就分不清当前处在哪个阶段。CoreBluetooth 的设计其实很对称中心设备Central负责扫描和连接外设Peripheral负责广播和响应主线一旦理清剩下的就是权限、参数和边界条件。下文把从零到能跑的最小链路写全依次覆盖 Info.plist 权限配置、CBCentralManager 扫描过滤、特征读写、MTU 分包、断线重连最后收在一个直接能用的 BleManager 封装上。新手按章节顺序敲完就能接到真实硬件熟手可以直接跳到第 4、5 章对照状态机维护和粘包处理。2. 先搭好 iOS 蓝牙开发的权限与扫描地基2.1 Info.plist 与蓝牙权限不配好直接闪退从 iOS 13 开始CoreBluetooth 的授权策略收紧任何访问蓝牙 API 的 App 都必须在 Info.plist 里声明NSBluetoothAlwaysUsageDescription否则调用CBCentralManager初始化时系统直接终止进程日志里只有一条This app has crashed because it attempted to access privacy-sensitive data without a usage description。开发阶段最容易漏的就是这条因为工程模板不会自动生成。iOS 12 及以下系统使用的是NSBluetoothPeripheralUsageDescription如果最低支持版本低于 iOS 13两个 key 都要配上。描述文案建议写清楚用途例如「用于连接心率计并同步运动数据」App Store 审核会读取这段文案写「用于连接蓝牙设备」这类空泛表述有被拒的先例。授权状态可以主动查询CBManager.authorization枚举有notDetermined、restricted、denied、allowedAlways四种注意 iOS 13 之前的authorized状态要留兜底分支。初始化时还有一个容易被忽略的选项CBCentralManagerOptionRestoreIdentifierKey。传入恢复标识符后应用在后台被系统挂起时蓝牙事件可以回调唤醒需配合 UIBackgroundModes不需要后台能力的项目可以不用传传了反而要额外处理willRestoreState的恢复逻辑。2.2 CBCentralManager 初始化与扫描参数常见做法是让控制器强持有CBCentralManager并遵循CBCentralManagerDelegateimport CoreBluetooth final class CentralHandler: NSObject, CBCentralManagerDelegate { private var central: CBCentralManager! override init() { super.init() central CBCentralManager( delegate: self, queue: nil, options: [CBCentralManagerOptionShowPowerAlertKey: true] ) } func centralManagerDidUpdateState(_ central: CBCentralManager) { guard central.state .poweredOn else { print(蓝牙状态异常: \(central.state.rawValue)) return } central.scanForPeripherals( withServices: [CBUUID(string: FFE0)], options: [CBCentralManagerScanOptionAllowDuplicatesKey: false] ) } }queue传nil表示回调在 main queue 执行UI 更新最省事扫描数据量大时可以传自定义串行队列回到 UI 线程再刷新界面。ShowPowerAlert设为 true 时用户关闭蓝牙会看到系统弹窗比自己在界面里提示省心。scanForPeripherals的withServices传nil会扫到周围所有 BLE 设备回调频繁且耗电常见做法是只扫描目标服务 UUID让系统做硬件级过滤。AllowDuplicates默认 false表示同一设备广播只上报一次需要做 RSSI 趋势判断或广播内动态数据时才改成 true。提示模拟器上central.state会停在 unsupportedCoreBluetooth 调试请直接上真机。iOS 面试题里问到 iOS 蓝牙开发大概率会考centralManagerDidUpdateState的状态对应关系这张表可以直接背CBManagerStaterawValue含义与处理unknown0初始态等待下一次回调resetting1系统蓝牙服务重启必要时重建 centralunsupported2设备不支持 BLE模拟器常见unauthorized3权限被拒引导去系统设置poweredOff4蓝牙关闭提示用户poweredOn5可以开始扫描2.3 从广播数据里认出你要的设备扫描回调centralManager(_:didDiscover:advertisementData:rssi:)的三个参数各有用处peripheral是后续连接的句柄advertisementData是设备主动广播的键值对RSSI是信号强度负值越接近 0 越近。识别设备不能只看peripheral.name很多硬件广播时不带 Local Namefunc centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String: Any], rssi RSSI: NSNumber) { let localName advertisementData[CBAdvertisementDataLocalNameKey] as? String let manufacturerData advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data let serviceUUIDs advertisementData[CBAdvertisementDataServiceUUIDsKey] as? [CBUUID] guard let localName, localName.hasPrefix(TT-) else { return } guard RSSI.intValue -80 else { return } targetPeripheral peripheral central.stopScan() }广播字典的 key 是固定的除了上面三个还有CBAdvertisementDataIsConnectableKey是否可连接和CBAdvertisementDataTxPowerLevelKey发射功率。需要按厂商自定义数据过滤时解析ManufacturerData的前两个字节 Company ID与蓝牙 SIG 的成员编号对应。过滤逻辑要轻不要在didDiscover里做字符串切割或转换提前把目标前缀、UUID 编译成常量不满足条件直接 return。3. 连接外设并完成服务、特征的发现与读写3.1 连接是异步的状态机要自己维护connect(_:options:)调用后不会立刻成功结果通过didConnect或didFailToConnect通知。从发现设备到可读写中间隔着连接成功、服务发现、特征发现三步每步都有独立回调回调里再触发下一步很容易造成时序错乱。所以要维护一个显式状态机disconnected、connecting、discovering、ready 四态回调里先判断当前状态再推进。连接参数里值得关注的是CBConnectPeripheralOptionNotifyOnConnectionKey和CBConnectPeripheralOptionNotifyOnDisconnectionKey都设为 true 后App 在后台也能收到连上/断开回调。系统不提供连接超时机制常见做法是发起连接时同时起一个 5 秒的 DispatchWorkItem超时后调用cancelPeripheralConnection并复位状态enum ConnState { case disconnected, connecting, discovering, ready } private var state: ConnState .disconnected private var connectTimer: DispatchWorkItem? func connect(_ peripheral: CBPeripheral) { state .connecting peripheral.delegate self central.connect(peripheral, options: [ CBConnectPeripheralOptionNotifyOnDisconnectionKey: true ]) let work DispatchWorkItem { [weak self] in guard let self, self.state .connecting else { return } self.central.cancelPeripheralConnection(peripheral) self.state .disconnected } connectTimer work DispatchQueue.main.asyncAfter(deadline: .now() 5, execute: work) } func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) { connectTimer?.cancel() state .discovering peripheral.discoverServices([CBUUID(string: FFE0)]) } func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) { state .disconnected }discoverServices不建议传 nil服务数量多时会浪费一次握手周期明确知道服务 UUID 就传数组。每次didConnect后peripheral.delegate都要重新赋值重连时外设对象可能是新实例委托不会自动保留。3.2 特征属性表读、写、通知到底支不支持服务CBService之下是特征CBCharacteristicBLE 的数据读写最终都落在特征上。每个特征声明了一组属性决定能对它做什么。判断能力要用characteristic.properties不要凭 UUID 猜同一 UUID 在不同固件版本里的属性可能不一样属性能力对应调用.read主动读取当前值peripheral.readValue(for:).write带应答写入writeValue(_:for:type:.withResponse).writeWithoutResponse无应答写入writeValue(_:for:type:.withoutResponse).notify订阅值变化通知setNotifyValue(true, for:).indicate带确认的通知同样走setNotifyValue.broadcast特征值广播一般不用于数据交互写数据前先做属性检查避免向只读特征写入时收到错误guard characteristic.properties.contains(.write) else { return }。无应答写入适合高频传感器数据速度快但没有失败反馈带应答写入适合指令下发每个包都有链路层确认吞吐量略低。硬件端常用的搭配是「写一个命令特征、订阅一个数据特征」命令通道用 .write数据通道用 .notify。iOS 面试题如果追问 iOS 蓝牙开发常会问这两种写法的差异答案核心是是否等待对端 ACK、吞吐量差别、以及 .withoutResponse 需要 App 自行做分包节流。3.3 写数据与订阅通知的完整代码发现特征横跨两个连续回调先didDiscoverServices再对每个服务调discoverCharacteristicsfunc peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) { for service in peripheral.services ?? [] { if service.uuid CBUUID(string: FFE0) { peripheral.discoverCharacteristics(nil, for: service) } } } func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) { for ch in service.characteristics ?? [] { switch ch.uuid.uuidString { case FFE1: writeChar ch peripheral.writeValue(Data([0x01, 0x02, 0x03]), for: ch, type: .withResponse) case FFE2: notifyChar ch peripheral.setNotifyValue(true, for: ch) default: break } } }写入结果在didWriteValueFor里确认error 为 nil 才算成功设备主动上报的数据和readValue的结果统一走didUpdateValueForfunc peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) { guard error nil, let value characteristic.value else { return } var bytes [UInt8](value) let type bytes.removeFirst() // 第一字节是帧类型 handlePacket(type: type, payload: Data(bytes)) } func peripheral(_ peripheral: CBPeripheral, didWriteValueFor characteristic: CBCharacteristic, error: Error?) { if let error { print(写入失败: \(error.localizedDescription)) } }注意didUpdateValueFor同时承载主动读和通知两种来源区分方式看characteristic.isNotifying。解析前把characteristic.value拷贝成新 Data不要持有特征对象引用等到下次回调系统会复用缓冲区。数据频率超过 50 Hz 时解析逻辑丢到串行队列避免阻塞主线程。4. iOS 蓝牙开发最常见的坑与调试手段4.1 连接频繁断开后台模式与系统弹窗连接一会就断第一嫌疑是 App 进了后台。iOS 默认后台会挂起蓝牙回调需要到 Signing Capabilities 里加 UIBackgroundModes 的bluetooth-centralApp 作为中心或bluetooth-peripheralApp 作为外设。加上之后配合第 2 章的 RestoreIdentifier系统才能在后台维持连接并唤醒 App。第二个嫌疑是系统蓝牙资源被其他 App 抢占。代码层面能做的只有区分断开原因判断系统主动断开error 为 nil还是链路异常error 非 nil再决定是否静默重连。硬件休眠唤醒本来就会断开一次不要收到断开就弹窗。断开错误可以按 error.code 归类error.codeSwift 符号常见场景1.operationCancelled主动 cancel 连接2.notConnected读写时外设未连接4.timeout操作超时5.peripheralDisconnected对端断开9.connectionFailed连接失败如超出范围4.2 数据粘包与 MTU分包发送怎么算BLE 单包最大长度是连接后协商出来的不是固定 20 字节。iOS 真机上常见 185 字节老硬件可能只有 27 字节。分包不要硬编码长度用peripheral.maximumWriteValueLength(for:)动态取值func send(data: Data, to peripheral: CBPeripheral, char: CBCharacteristic) { let type: CBCharacteristicWriteType .withResponse let maxLen peripheral.maximumWriteValueLength(for: type) var offset 0 while offset data.count { let length min(maxLen, data.count - offset) let chunk data.subdata(in: offset..(offset length)) peripheral.writeValue(chunk, for: char, type: type) offset length } }.withResponse模式下系统会按序排队上面的循环可以连续发如果改成.withoutResponse必须自己维护发送窗口比如每包间隔 20ms或先查peripheral.canSendWriteWithoutResponse否则低端蓝牙芯片的缓冲区会溢出丢包。接收端的粘包是反方向的问题设备一次上报的数据可能要跨多个通知包拼成一个完整指令。常见做法是定义帧格式[帧头0xAA][长度][负载][校验]在didUpdateValueFor里累积缓冲长度够了再截取解析。注意.withResponse分包循环里不要手动加延时系统以链路层 ACK 为准人为 sleep 只会拖慢整体吞吐。4.3 断线重连与 RSSI 过滤重连不能无脑高频循环硬件的连接参数里通常有 supervision timeout刚断开的设备短时间内很难立刻重连。后台重连的常见做法是退避第一次 1 秒之后 2、4、8 秒封顶重连成功再重置func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) { guard shouldReconnect else { return } retryCount 1 let delay min(pow(2.0, Double(retryCount)), 8.0) DispatchQueue.global().asyncAfter(deadline: .now() delay) { [weak self] in guard let self, self.central.state .poweredOn else { return } self.central.scanForPeripherals(withServices: [self.serviceUUID]) } }重连目标用peripheral.identifierUUID而不是name名字可以变identifier 在系统内是稳定的身份标识。RSSI 过滤要跟业务耦合手环、门锁这类设备 -80 dBm 以下基本不可用信标类场景反而要保留远距离信号做范围判断。RSSI 是短时均值、抖动大别用单次值卡阈值取 3 次采样的中位数更可靠。4.4 用日志和自动化脚本提高排查效率调试 iOS 蓝牙开发日志要覆盖全生命周期状态变化、扫描命中、连接成功与失败、服务发现、特征发现、每次读写的数据长度与结果。数据用 hex 字符串打印不要直接输出 Data 的 description。常见做法是包一层BTLog开关release 包直接裁剪。权限弹窗的重复测试交给 UI 自动化用 XCUITest 的addUIInterruptionMonitor(withDescription:)监控系统弹窗并点击 Allow可以自动跑完「拒绝授权 → 重新授权」两条路径。真机上先用 LightBlue 这类通用调试工具复现读写流程能快速定位是硬件问题还是 iOS 端代码问题。这个思路同样适用 iOS 面试题里的场景题面试官问「连接频繁断开怎么排查」把日志分层、错误码归类、工具链验证三步讲清楚比背 API 列表有用得多。5. 一个直接能用的 BleManager 封装与调试技巧最后给一个可控的最小封装把 Central 和 Peripheral 的 delegate 收敛到一个类里对外只暴露connect、send和回调闭包业务层不再关心回调嵌套。这个结构也对应组件化开发里的基础层划分蓝牙模块只提供连接与收发原语业务状态由上层自己维护final class BleManager: NSObject { static let shared BleManager() private var central: CBCentralManager! private var peripheral: CBPeripheral? private var writeChar: CBCharacteristic? private var namePrefix var onStateChanged: ((String) - Void)? var onDataReceived: ((Data) - Void)? override private init() { super.init() central CBCentralManager(delegate: self, queue: nil) } func connect(namePrefix: String) { self.namePrefix namePrefix central.scanForPeripherals(withServices: nil) } func send(_ data: Data) { guard let peripheral, let writeChar, peripheral.state .connected else { print(设备未连接发送失败) return } peripheral.writeValue(data, for: writeChar, type: .withResponse) } } extension BleManager: CBCentralManagerDelegate, CBPeripheralDelegate { // didDiscover 里按 namePrefix 过滤并 stopScan // didConnect 之后的服务发现与特征发现流程与第 3 章一致 // 在 didDiscoverCharacteristicsFor 里保存 writeChar 和 notifyChar }封装时有两个细节值得注意。一是每个 delegate 回调都要做[weak self]捕获并在didConnect里重新设置peripheral.delegate self防止重连后回调丢失。二是send内部必须判断peripheral.state .connected设备没连接时不要静默失败打日志并把错误回抛给业务层界面才能给出正确提示。调试技巧写入不生效时按顺序确认三件事——特征属性里是否包含对应的 write 类型、maximumWriteValueLength是否被超长数据绕过、固件端是否真的收到了空中包。三步做完九成写入问题都有结论。如果怀疑 iOS 系统缓存了旧特征值先cancelPeripheralConnection断开等 2 秒再重连必要时重启蓝牙开关刷新系统缓存。本文还有配套的精品资源点击获取