Zigbee Home Automation（ZHA）完整配置
什么是 ZHA
Zigbee Home Automation（简称 ZHA）是 Home Assistant 内置的 Zigbee 集成。它可以让你通过一个 USB 适配器接入数百种 Zigbee 设备——小米 Aqara、飞利浦 Hue、宜家 Trådfri、SONOFF、Hieee、Trust 等品牌都原生支持。
Home Assistant OS 上 ZHA 是零配置的——插上 USB 适配器，ZHA 自动发现，点两下就完成。
第一步：选择 Zigbee USB 适配器
ZHA 支持绝大多数 Zigbee 适配器，但不同芯片组的兼容性差异很大：
推荐适配器
| 适配器 | 芯片 | 优点 | 缺点 |
|---|---|---|---|
| Home Assistant Connect ZBT-1 | CC2531 | 官方推荐，可升级 Thread 固件 | 价格稍高 |
| SONOFF ZBDongle-P | CC2652P | 性价比高，信号好 | 偶尔需要手动指定固件 |
| SONOFF ZBDongle-E | EFR32MG21 | Thread 支持，未来可刷 Matter | 固件更新稍麻烦 |
| IKEA Dirigera Hub | - | IKEA 官方 | 价格高，扩展性差 |
避坑清单
- 不要用太老的 CC2530——RAM 太小，网络大了经常掉设备
- 不要用 EZSP 芯片旧版 EZSP 6.x——ZHA 不完全支持，需要升级到 EZSP 8.x+
- 适配器务必用 USB 延长线插在主机外面，不要直接插在树莓派上——USB 3.0 会干扰 Zigbee 2.4GHz 信号
第二步：插入适配器并发现
- 把适配器插到树莓派/主机上
- Home Assistant 会自动发现（Settings → Devices & services 应该能看到新适配器提示）
- 点击 Configure → 选择 Zigbee Home Automation → 选择适配器的串口路径（如
/dev/ttyUSB0） - 选择芯片类型（如 Silicon Labs EZSP、Texas Instruments Z-Stack）
- 不要创建新网络——首次使用选创建，之后换适配器可以恢复旧网络
第三步：配对设备
ZHA 有两种配对方式：
方式一：在 ZHA 集成页触发 Pairing Mode
- Settings → Devices & services → Zigbee Home Automation → 点击进去
- 顶部找到 + Add device → Search for new devices
- 此时 ZHA 进入 Pairing 模式（这个状态持续 1 分钟）
- 把你的 Zigbee 设备（灯泡、传感器等）恢复出厂设置（长按重置按钮 5~10 秒，或按品牌说明做）
- 设备自动被 ZHA 发现，Home Assistant 弹出配对成功的提示
- 给设备命名、分配区域
方式二：让设备自己广播配对
某些设备（如刚买来的 Zigbee 灯泡）出厂就是配对模式——上电后自动广播。ZHA 打开 Pairing Mode 后会自动发现。
ZHA 支持哪些设备类型
ZHA 自动识别并创建对应的实体：
- 灯（
light.xxx）：支持开/关、亮度、色温、RGB - 开关（
switch.xxx）：开/关 - 传感器（
sensor.xxx/binary_sensor.xxx）：温度、湿度、人体感应、门窗开合、光照等 - 插座（
switch.xxx） - 温控器（
climate.xxx） - 门锁（
lock.xxx） - 报警器（
alarm_control_panel.xxx） - 覆盖设备（
cover.xxx）：窗帘、车库门
常见问题
配对时 ZHA 找不到设备
- 确认适配器被识别了（Settings → System → Hardware → 能看到 Zigbee 适配器）
- 确认设备已恢复出厂（很多设备需要长按重置按钮 10 秒以上）
- 设备距离适配器不要超过 3 米——首次配对越近越好，之后 Zigbee Mesh 网络会自动扩展覆盖
- 如果 USB 3.0 干扰，试试把适配器用延长线拖远
设备配对后经常掉线
- 适配器 USB 供电不足（树莓派尤其严重）——换官方电源或给适配器加独立电源
- 距离太远——Zigbee 节点（其他灯、插座）可以充当中继，多放几个设备就好了
- 频道干扰——2.4GHz 有很多拥挤的 Wi-Fi 频道，在 ZHA 设置里换一个 Zigbee 频道试试（ZHA 设置页 → Zigbee settings → Channel）
关于 ZHA vs. Zigbee2MQTT
ZHA 和 Zigbee2MQTT（Z2M）是 Home Assistant 接入 Zigbee 设备的两大方案：
| 对比项 | ZHA | Zigbee2MQTT |
|---|---|---|
| 集成方式 | Home Assistant 内置 | 通过 MQTT 中间件 |
| 支持设备 | 几百种 | 上千种（更全） |
| 配置难度 | 低（零代码） | 中（需要装 MQTT Broker + Z2M 容器） |
| UI 控制 | Home Assistant 直接 | Z2M 有独立 Web UI |
| 固件升级 | 支持 | 支持（更强大） |
| 推荐程度 | 新手首选 | 进阶玩家首选 |
两者都很成熟，选哪个主要看你自己的设备是否在 Z2M 支持列表里。Z2M 支持的设备范围确实更全，但 ZHA 在 Home Assistant OS 上是内置的，省了额外装 MQTT 和 Z2M 的步骤。