Zigbee / Matter 设备配对失败修复
配对流程概述
Home Assistant 接入新设备通常分两步：
1. 设备恢复出厂 → 进入配对模式
2. Home Assistant 打开配对模式 → 发现设备 → 加入网络任何一步出问题都会导致配对失败。下面按协议类型分述。
Zigbee 配对失败
设备侧（设备不响应配对）
Zigbee 设备配对要点：
| 品牌 | 恢复出厂 | 进入配对 |
|---|---|---|
| Aqara（小米绿米） | 长按重置按钮 5~10 秒 | 恢复出厂后自动进入 |
| Philips Hue | Hue Bridge 上按一下 Link 按钮 | 自动发现 |
| SONOFF Zigbee | 长按 5 秒 | 自动 |
| IKEA | 长按 ONOFF 按钮 10 秒 | 自动 |
| Xiaomi Mi | 长按重置 5 秒 | 自动 |
适配器侧
- ZHA 或 Zigbee2MQTT（Z2M） 是否在运行
- USB 适配器是否被识别（Serial port 有
/dev/ttyUSB0或/dev/ttyACM0） - ZHA 设置 → 配对模式是否打开（Settings → Devices & services → ZHA → Add device → Search）
- Z2M Web UI → Pairing 模式是否打开
常见配对错误
错误 1：ZHA 打开配对后看不到新设备
- 设备离适配器太远 → 拿到同一房间、< 3 米距离再配对
- USB 适配器被 USB 3.0 干扰 → 用延长线拖远
- Zigbee 网络频道拥挤 → ZHA 设置里换频道试试（换了频道所有现有设备会失联，要重配对）
- 设备不是 Zigbee 设备（有些小米传感器是 BLE 而非 Zigbee）
错误 2：配对到一半失败
- 电池低电量 → 换电池再试
- 设备已在另一个 Zigbee 网络里 → 先恢复出厂
- 配对超时（ZHA 默认 1 分钟，某些设备需要更长） → 打开 ZHA 配对后立刻按设备重置
错误 3：配对成功但设备马上显示 unavailable
- 配对时设备信号好，但实际位置太远
- 配对后立即把设备搬到安装位置 → 设备需要时间和 Mesh 网络重新建立连接
- 等 5~10 分钟再看
用 Z2M 代替 ZHA（可选）
如果 ZHA 反复配不上某些设备，Zigbee2MQTT（Z2M） 通常更靠谱：
- Home Assistant OS：Settings → Apps → 搜索 Zigbee2MQTT → Install
- Z2M 打开后 → 在 Z2M Web UI 里配对 → 自动推送到 Home Assistant
- Z2M 支持的设备明显比 ZHA 多（~3000 种 vs ~1000 种）
Matter 配对失败
Matter 配对有三种方式：
- 扫码：扫描设备上的 Matter QR 码（最可靠）
- 手动码：输入设备上的 11 位手动码
- NFC 标签：设备靠近手机/扫描器（较少用）
前置条件
- Matter Server App 是否在运行（Settings → Apps → Matter Server）
- Thread Border Router 是否在线（Home Assistant SkyConnect、HomePod mini、Google Nest Hub 都行）
- 手机或 Home Assistant 和设备在同一网络
- 设备确实支持 Matter（包装上有 Matter 标志）
常见配对错误
错误 1：Matter Server 找不到 QR 码
- 码不对或模糊 → 用手动码输入
- 设备二维码旁边有"Manual Setup Code"或"PIN Code" → 手动输入
错误 2：Thread 设备配对后离线
- 需要 Thread Border Router → 加一个
- 设备和 Border Router 距离 → 不要太远
- 确认设备支持 Matter over Thread
错误 3：设备同时被多个 Matter 控制器管理
Matter 设备最多可以同时被 3 个控制器控制（Home Assistant + Apple HomeKit + Google Home 典型就是 3 个）。超过 3 个就配不上。解决：从不需要的控制器里移除设备。
Z-Wave 配对失败
Z-Wave 配对要点
Z-Wave 的配对（Inclusion）要求设备距离适配器 1 米以内——Z-Wave 首次配对距离非常严格。
- Z-Wave JS UI → Devices → + Add device
- 选安全级别（推荐 S2 Authenticated）
- Z-Wave JS 进入 Inclusion 模式
- 把 Z-Wave 设备拿到距离适配器 1 米内
- 按设备重置按钮或插电
- Z-Wave JS 发现 → 输入 S2 PIN 码（某些设备需要） → 完成
Z-Wave 配对失败的常见原因
- 距离太远：拿到同一房间、贴脸距离
- 设备已在其他 Z-Wave 网络：先恢复出厂 → 在 Z-Wave JS 里做 Exclusion → 再 Inclusion
- 适配器和设备地区不匹配：美国 908MHz、欧洲 868MHz、中国 800MHz。买设备时要和适配器地区对应
- S2 PIN 错了：某些设备首次配对需要 PIN，在说明书或设备标签上。PIN 输错 → 从 Z-Wave JS UI 移除设备后重新 Inclusion
WiFi 设备配对
WiFi 设备（Sonoff、Yeelight、Philips Hue、小米 MIoT）的配对方式各不同：
方式一：局域网直连（推荐）
某些设备（Philips Hue、Sonoff 刷 Tasmota、Yeelight）支持局域网 API，Home Assistant 直接通过局域网接入，不需要云账号。
- Philips Hue：Settings → Devices & services → Add integration → 搜索 Hue → 发现 Bridge → 按一下 Bridge 顶部按钮 → 完成
- Yeelight：Settings → Devices & services → Add integration → 搜索 Yeelight → 自动发现
- Sonoff（原厂固件）：Home Assistant 集成方式有限 → 刷 Tasmota 后变 MQTT 设备
方式二：云账号
小米 MIoT、Amazon Alexa、Google Home 的设备需要 Home Assistant 登录对应云账号：
- 小米：HACS → 装 Xiaomi MIoT → 用小米账号登录 → 自动拉取设备
- 注意：小米集成在中国区有时 Token 不稳定
WiFi 设备配对失败排查
- 设备是否恢复出厂？（长按重置 5~10 秒）
- Home Assistant 和设备是否在同一 WiFi（不同 SSID 或访客网络可能不通）
- 在 Home Assistant 机器上直接
ping 设备IP看看通不通 - 某些 WiFi 设备只支持 2.4GHz —— 不要用 5GHz WiFi
- 路由器是否开启了"AP 隔离"——会导致设备之间不互通，需要关闭
恢复出厂设置通用方法
绝大多数智能设备的恢复出厂都是长按重置按钮 5~10 秒：
- 有些设备重置后会闪烁（表示进入配对模式）
- 有些设备重置后需要重新上电
- 如果 10 秒没反应 → 试试长按 15~20 秒（有些设备时间特别长）
- 如果还是不行 → 查设备说明书或厂商官方的 Support 文档
配对始终失败的终极手段
如果反复配对都失败：
- 手动清理 Home Assistant 的设备缓存
- Settings → Devices & services → 移除所有该设备可能相关的集成
- Developer Tools → Services → 调用
homeassistant.reload_config_entry - 重启 Home Assistant
- 全新刷写 Home Assistant OS
- 备份快照
- 重刷系统
- 先只装一个设备测试配对
- 确认配对成功后再恢复快照（或手动重新配置）
- 换 USB 适配器
- 如果是 Zigbee/Z-Wave 配对反复失败，可能是适配器质量问题
- 换个口碑好的（Home Assistant Connect ZBT-1、SONOFF ZBDongle-P、Aeotec Z-Stick）