微信小程序蓝牙分包传输实战：如何用wx.setBLEMTU突破20字节限制（附完整协议设计）

微信小程序蓝牙大容量数据传输：突破20字节限制的MTU协商与高效分包协议设计

如果你曾经尝试过用微信小程序给低功耗蓝牙设备发送一个稍微大点的文件，比如一个几十KB的固件包，那你一定对那个令人头疼的“20字节限制”印象深刻。每次只能发20个字节，一个100KB的文件要分成5000多个包，这传输效率简直让人抓狂。更别提在传输过程中可能出现的各种连接中断、数据错乱问题了。

但好消息是，这个限制其实是可以被打破的。通过合理的MTU协商和精心设计的通信协议，我们完全可以把单次传输的数据量提升到200字节甚至更多，让固件升级这样的操作从“煎熬”变成“流畅”。我最近在一个智能硬件项目中就成功实现了这一点，把传输效率提升了10倍以上，整个过程稳定可靠。

这篇文章就是要把我踩过的坑、总结的经验，以及最终跑通的完整方案分享给你。无论你是要做OTA升级、大文件传输，还是任何需要蓝牙传输大量数据的场景，这里面的思路和代码都能直接拿来用。

1. 理解BLE传输限制与MTU协商机制

在深入代码之前，我们需要先搞清楚几个关键概念。很多人一提到微信小程序蓝牙开发，第一反应就是“20字节限制”，但这个说法其实不够准确。

1.1 BLE协议栈的数据传输层次

蓝牙低功耗的数据传输并不是简单的一层，而是由多个协议层组成的。当你调用wx.writeBLECharacteristicValue时，数据会经过这样的路径：

应用层数据 → ATT协议层 → L2CAP层 → 物理层

那个著名的“20字节限制”实际上来自ATT协议层。在标准的BLE规范中，ATT_MTU（Attribute Protocol Maximum Transmission Unit）的默认值确实是23字节，但其中3个字节被用于协议头，所以留给应用数据的只有20字节。

但这里有个关键点：这个值是可以协商的。设备连接后，客户端（你的小程序）和服务器端（蓝牙设备）可以协商一个更大的MTU值。这就是wx.setBLEMTU这个API存在的意义。

1.2 MTU协商的实际限制

从微信官方文档看，wx.setBLEMTU的说明是“仅安卓系统5.1以上版本有效，iOS因系统限制不支持”。这导致很多开发者直接放弃了MTU协商，认为iOS上没戏。

但实际情况要复杂得多：

• Android端：确实需要通过wx.setBLEMTU主动协商，范围是22-512字节
• iOS端：系统会自动协商MTU，通常可以到256字节左右，但小程序层面无法主动设置

我在实际测试中发现，不同设备、不同系统版本的表现差异很大：

注意：这里说的“默认MTU”是指连接建立后的初始值，不是理论上的23字节。很多现代设备在连接时会自动协商一个更大的值。

1.3 实际可用的数据载荷计算

即使协商了更大的MTU，也不是所有字节都能用来传输你的应用数据。我们需要扣除协议开销：

实际可用载荷 = 协商的MTU - ATT头(3字节) - L2CAP头(4字节)

举个例子，如果你协商了220字节的MTU：

• ATT层可用：220 - 3 = 217字节
• L2CAP层可用：217 - 4 = 213字节

但为了保险起见，我通常会在应用层再留一些余量。在我的项目中，最终确定每个数据包携带196字节的有效载荷，这个数字经过多次实测验证，在iOS和Android上都能稳定工作。

// 计算实际可用的数据包大小
function calculatePacketSize(mtu) {
  // MTU - ATT头(3) - L2CAP头(4) - 安全余量(2)
  const available = mtu - 3 - 4 - 2;
  
  // 为了对齐和计算方便，取整到合适的值
  // 196是一个经过验证的稳定值
  return Math.min(available, 196);
}

// 在实际使用中
const effectiveMTU = 220; // 协商后的MTU
const payloadSize = calculatePacketSize(effectiveMTU); // 196字节

2. 双端兼容的MTU协商策略

既然iOS和Android在MTU处理上如此不同，我们就需要一个智能的策略来同时覆盖两个平台。

2.1 平台检测与差异化处理

首先，我们需要准确判断当前运行的是哪个平台：

// 获取设备信息
const systemInfo = wx.getSystemInfoSync();
const platform = systemInfo.platform; // 'ios' 或 'android'
const system = systemInfo.system; // 如 'iOS 15.4' 或 'Android 13'

// 更精细的平台判断
function getPlatformInfo() {
  const info = wx.getSystemInfoSync();
  return {
    platform: info.platform,
    system: info.system,
    version: info.version,
    brand: info.brand,
    model: info.model
  };
}

// 根据平台采取不同的MTU策略
async function setupMTU(deviceId) {
  const platformInfo = getPlatformInfo();
  
  if (platformInfo.platform === 'ios') {
    // iOS平台：不主动设置MTU，依赖系统自动协商
    console.log('iOS设备，使用系统自动协商的MTU');
    
    // 可以尝试读取当前的MTU值
    try {
      const res = await wx.getBLEMTU({ deviceId });
      console.log(`当前MTU: ${res.mtu}字节`);
      
      // 根据实际MTU调整分包大小
      const packetSize = calculatePacketSize(res.mtu);
      return packetSize;
    } catch (err) {
      console.warn('获取MTU失败，使用默认值');
      return 196; // iOS上比较安全的默认值
    }
    
  } else if (platformInfo.platform === 'android') {
    // Android平台：主动协商MTU
    console.log('Android设备，尝试协商更大的MTU');
    
    // 尝试设置MTU，从较小值开始逐步尝试
    const mtuValues = [220, 247, 512]; // 尝试的值
    let negotiatedMTU = 23; // 默认值
    
    for (const mtu of mtuValues) {
      try {
        const result = await new Promise((resolve, reject) => {
          wx.setBLEMTU({
            deviceId,
            mtu,
            success: resolve,
            fail: reject
          });
        });
        
        negotiatedMTU = result.mtu;
        console.log(`成功设置MTU为: ${negotiatedMTU}字节`);
        break;
        
      } catch (err) {
        console.warn(`设置MTU为${mtu}失败:`, err);
        continue;
      }
    }
    
    // 根据协商结果计算可用载荷
    const packetSize = calculatePacketSize(negotiatedMTU);
    return packetSize;
    
  } else {
    // 其他平台（如开发工具）
    console.warn('未知平台，使用保守值');
    return 20; // 最保守的值
  }
}

2.2 Android 14的特殊处理

在实际开发中，我发现Android 14上wx.setBLEMTU有时会失败，错误码是1500104。这可能是系统权限或蓝牙栈的变更导致的。针对这种情况，我设计了一个重试机制：

// 带重试的MTU设置函数
async function setMTUWithRetry(deviceId, targetMTU, maxRetries = 3) {
  let lastError = null;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      console.log(`第${attempt}次尝试设置MTU为${targetMTU}`);
      
      const result = await new Promise((resolve, reject) => {
        wx.setBLEMTU({
          deviceId,
          mtu: targetMTU,
          success: (res) => {
            // 有些设备即使返回成功，实际MTU可能没变
            // 这里可以再验证一下
            setTimeout(() => {
              wx.getBLEMTU({
                deviceId,
                success: (checkRes) => {
                  console.log(`验证MTU: 请求${targetMTU}, 实际${checkRes.mtu}`);
                  resolve(checkRes);
                },
                fail: () => resolve(res) // 如果获取失败，至少认为设置成功了
              });
            }, 100);
          },
          fail: reject
        });
      });
      
      // 如果设置成功，返回结果
      if (result.mtu >= targetMTU) {
        console.log(`MTU设置成功: ${result.mtu}字节`);
        return result;
      } else {
        console.warn(`MTU设置不完整: 期望${targetMTU}, 实际${result.mtu}`);
        lastError = new Error(`MTU协商不完整: ${result.mtu}`);
      }
      
    } catch (err) {
      console.warn(`第${attempt}次尝试失败:`, err);
      lastError = err;
      
      // 如果不是最后一次尝试，等待一段时间再重试
      if (attempt < maxRetries) {
        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
      }
    }
  }
  
  // 所有尝试都失败
  throw lastError || new Error('MTU设置失败');
}

// 在连接成功后调用
async function onBLEConnected(deviceId) {
  try {
    // 先尝试设置较大的MTU
    const result = await setMTUWithRetry(deviceId, 220);
    
    // 如果失败，尝试较小的值
  } catch (err) {
    console.error('MTU协商失败，使用默认值:', err);
    
    // 降级方案：使用默认的20字节分包
    // 或者尝试更小的MTU值
    try {
      const fallbackResult = await setMTUWithRetry(deviceId, 100);
      console.log('降级MTU设置成功:', fallbackResult.mtu);
    } catch (fallbackErr) {
      console.error('降级MTU也失败，使用最保守方案');
    }
  }
}

2.3 连接时机的优化

MTU协商必须在连接建立后立即进行，但也不能太早。我发现最佳时机是在wx.createBLEConnection成功回调中，但在获取服务之前：

wx.createBLEConnection({
  deviceId,
  timeout: 15000, // 适当延长超时时间
  success: async (res) => {
    console.log('蓝牙连接成功');
    
    // 立即开始MTU协商
    try {
      const packetSize = await setupMTU(deviceId);
      console.log(`确定的分包大小: ${packetSize}字节`);
      
      // 保存到全局状态，供后续使用
      this.setData({ packetSize });
      
      // 继续获取服务
      this.getBLEDeviceServices(deviceId);
      
    } catch (mtuErr) {
      console.error('MTU协商失败，但继续流程:', mtuErr);
      // 即使MTU失败，也继续后续流程，使用默认值
      this.getBLEDeviceServices(deviceId);
    }
  },
  fail: (err) => {
    console.error('蓝牙连接失败:', err);
    wx.showToast({ title: '连接失败', icon: 'error' });
  }
});

3. 高效可靠的分包协议设计

有了合适的MTU，接下来就是如何设计通信协议了。一个好的协议不仅要能传输数据，还要保证数据的完整性和顺序。

3.1 协议帧结构设计

我设计的协议帧包含以下几个部分：

[帧头][长度][命令/类型][索引][总数][数据长度][数据内容][校验和]

具体到字节级别：

这个设计有几个关键考虑：

1. 帧头同步：0xFFFE作为起始标识，帮助接收方找到帧的开始位置
2. 长度字段：让接收方知道该读取多少数据
3. 索引和总数：支持乱序重组和进度显示
4. 数据长度：实际数据可能小于最大容量，需要明确标识
5. 校验和：最简单的错误检测机制

3.2 协议实现代码

下面是完整的协议封装和解包代码：

// 协议常量定义
const PROTOCOL = {
  HEADER: 0xFFFE,
  TYPE_FIRMWARE_INFO: 0x01,
  TYPE_DATA_PACKET: 0x02,
  MAX_PAYLOAD_SIZE: 196, // 根据MTU调整
};

// 构建固件信息包（第一个包）
function buildFirmwareInfoPacket(firmwareInfo) {
  const {
    totalPackets,      // 总包数
    totalSize,         // 文件总大小（字节）
    md5,              // 文件MD5
    firmwareType = 0x01 // 固件类型
  } = firmwareInfo;
  
  // 将数值转换为16进制字符串，并补齐长度
  const totalPacketsHex = totalPackets.toString(16).padStart(4, '0');
  const totalSizeHex = totalSize.toString(16).padStart(4, '0');
  
  // 构建数据部分（不包含Header和CRC）
  const dataPart = 
    PROTOCOL.TYPE_FIRMWARE_INFO.toString(16).padStart(2, '0') +
    totalPacketsHex +