Web Bluetooth API允许网页直接与附近的蓝牙低功耗设备交互，在物联网控制、硬件数据上报等场景中应用广泛，但发送数据时经常会出现写入失败、设备无响应等情况，需要针对性排查解决。
常见发送数据问题分类
发送数据失败的问题通常可以分为以下几类，排查时可以按顺序逐一验证：
- 连接状态异常：设备未保持连接、连接已断开但未被感知
- GATT服务特征不匹配：未找到正确的可写特征、特征权限不足
- 数据格式错误：发送的数据长度超过特征限制、数据类型不符合要求
- 浏览器兼容性问题：当前浏览器不支持对应API、部分特性未开启
分步排查流程
1. 验证设备连接状态
首先确认蓝牙设备是否处于稳定连接状态，很多发送失败的问题都是因为连接已经断开但代码没有处理断开事件导致的。可以通过以下方式检查：
// 监听蓝牙设备断开事件
device.addEventListener('gattserverdisconnected', (event) => {
console.log('蓝牙设备已断开连接', event);
// 这里可以添加重连逻辑
});
// 发送数据前检查连接状态
if (!device.gatt.connected) {
console.error('设备未连接，无法发送数据');
return;
}
2. 确认GATT服务和特征正确性
蓝牙设备的数据发送依赖特定的GATT服务和特征，需要确认获取到的特征支持写入操作，并且UUID匹配设备的说明文档。可以通过以下代码排查：
async function getWriteCharacteristic(device) {
try {
// 连接GATT服务器
const server = await device.gatt.connect();
// 获取目标服务，这里替换为实际的服务UUID
const service = await server.getPrimaryService('12345678-1234-1234-1234-1234567890ab');
// 获取可写特征，替换为实际的特征UUID
const characteristic = await service.getCharacteristic('abcdefab-1234-1234-1234-abcdefabcdef');
// 检查特征是否支持写入
const properties = characteristic.properties;
if (!properties.write && !properties.writeWithoutResponse) {
console.error('该特征不支持写入操作');
return null;
}
return characteristic;
} catch (error) {
console.error('获取GATT特征失败:', error);
return null;
}
}
3. 检查发送数据格式
不同的蓝牙特征对发送的数据有不同要求，比如有的限制最大长度为20字节，有的要求必须是ArrayBuffer格式，需要按照设备要求处理数据：
async function sendData(characteristic, data) {
try {
// 如果设备要求字符串格式，先转为ArrayBuffer
const encoder = new TextEncoder();
const buffer = encoder.encode(data).buffer;
// 检查数据长度是否超过特征限制
const maxLength = characteristic.value ? characteristic.value.byteLength : 20;
if (buffer.byteLength > maxLength) {
console.error(`发送数据长度超过限制，最大允许${maxLength}字节`);
return;
}
// 发送数据，根据特征支持的写入方式选择
if (characteristic.properties.writeWithoutResponse) {
await characteristic.writeValueWithoutResponse(buffer);
} else {
await characteristic.writeValueWithResponse(buffer);
}
console.log('数据发送成功');
} catch (error) {
console.error('数据发送失败:', error);
}
}
4. 排查浏览器兼容性
Web Bluetooth API目前仅在部分浏览器中支持，需要先检查当前环境是否支持该API：
if (!('bluetooth' in navigator)) {
console.error('当前浏览器不支持Web Bluetooth API');
// 可以提示用户更换Chrome、Edge等支持的浏览器
return;
}
常见问题解决方案汇总
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 调用发送方法直接报错 | 未获取蓝牙设备权限、设备未连接 | 先调用navigator.bluetooth.requestDevice获取设备，确认连接状态后再发送 |
| 数据发送后设备无响应 | 特征UUID错误、数据格式不符合设备要求 | 核对设备文档的GATT定义，调整数据格式和特征UUID |
| 偶尔发送失败 | 蓝牙信号不稳定、连接断开未重连 | 添加断开重连逻辑，发送前校验连接状态 |
| 部分浏览器无法使用 | 浏览器不支持该API | 引导用户使用Chrome、新版Edge等支持的浏览器，或添加降级方案 |
完整发送数据示例
以下是一个完整的发送数据流程示例，整合了上述排查逻辑：
async function sendBluetoothData() {
try {
// 1. 请求蓝牙设备
const device = await navigator.bluetooth.requestDevice({
filters: [{ name: '目标设备名称' }],
optionalServices: ['12345678-1234-1234-1234-1234567890ab'] // 替换为目标服务UUID
});
// 2. 监听断开事件
device.addEventListener('gattserverdisconnected', () => {
console.log('设备断开，尝试重连...');
});
// 3. 获取可写特征
const characteristic = await getWriteCharacteristic(device);
if (!characteristic) return;
// 4. 发送数据
const sendText = 'hello bluetooth';
await sendData(characteristic, sendText);
} catch (error) {
console.error('整体流程失败:', error);
}
}
实际开发中如果遇到发送数据问题，可以按照上述流程逐步排查，大部分问题都能快速定位并解决。如果问题仍然存在，可以查看浏览器的控制台报错信息，结合蓝牙设备的调试日志进一步分析。
Web_Bluetooth_APIBluetoothGATT蓝牙通信前端开发修改时间：2026-07-24 02:15:35