WLED Home Assistant 故障排除 智能家居

WLED 和 Home Assistant:常见问题和修复

Home Assistant 中 WLED 集成的修复方法:未被发现、“Unknown error occurred”、实体不可用、IP 变了、预设和播放列表不显示、分段作为实体以及固件更新。

作者:

Home Assistant 内置了 WLED 集成,通常不费什么事就能用:它找到灯,创建一个灯实体和几个控件,并保持同步。出问题时,原因通常是少数几种之一,其中几种已经在最近的 Home Assistant 版本中修复。所以第一个问题永远是:您用的是哪个 Home Assistant 版本?本页标注了改变每种行为的版本。

从头设置集成在官方文档里讲得很清楚。本页讲的是出了问题怎么办。

集成会创建什么

知道该期待什么,才更容易发现“缺失”的实体。每盏 WLED 灯您会得到:

实体是什么
Light灯本身,有颜色、亮度和效果列表。有多个分段时,每个分段各有一个 Light 实体
Main light仅在有多个分段时(或开启 Keep Main Light 时):整个设备的电源和整体亮度
Preset 和 Playlist select加载预设或启动播放列表
Color palette select每个分段一个,在 configuration 下
Live override selectOff、On 或 Until device restarts(与 WLED 的 live data override 相同)
Speed 和 Intensity number每个分段一组,即效果滑块
SwitchNightlight、Sync send、Sync receive,以及每个分段的 Reverse 和 Freeze
SensorEstimated current、Max current、LED count、IP。Uptime、空闲内存和 Wi-Fi 传感器存在但默认禁用
Restart 按钮和固件更新在 configuration 和 diagnostics 下

该集成需要 WLED 0.14.0 或更新版本。在更旧的固件上设置会失败。从 Home Assistant 2025.12 起它会明确说明;之前显示的是一条笼统的错误。

Home Assistant 没有发现 WLED

Home Assistant 通过 mDNS(zeroconf,_wled._tcp 服务)查找 WLED。以下情况下 Discovered 里什么都不会出现:

  • 灯和 Home Assistant 在不同的 VLAN 或子网。 除非路由器或反射器转发,mDNS 不跨子网。在有独立 IoT VLAN 的网络上这是最常见的原因。
  • WLED 的 mDNS 名称为空。 在 Config›WiFi & Network(WLED 16 之前叫 WiFi Setup)中,mDNS address 字段必须有名称(默认类似 wled-abcdef)。为空就意味着完全没有 mDNS。
  • 您的接入点隔离了 Wi-Fi 客户端(通常叫客户端隔离或 AP 隔离,访客网络上很常见)。
  • Home Assistant 自己的网络设置排除了灯所在的网卡。

您不需要发现功能。手动添加集成:Settings›Devices & services›Add integration›WLED,输入灯的 IP 地址。较新的版本也接受粘贴的 URL,并只保留主机部分。

如果不知道 IP:WLED 网页界面在 Info 里显示它,路由器会列出它,在 WLED Max 中它在灯的设置里的“设备信息”部分,标为“IP 地址”。

添加 WLED 时出现“Unknown error occurred”

到 Home Assistant 2026.9 为止,设置流程只识别两种问题:“无法连接”和(从 2025.12 起)“固件太旧”。其他一切都以 Unknown error occurred 结束。实际上“其他一切”是:

  • 灯上的预设文件损坏。 集成在设置时读取灯的预设,presets.json 里无效的 JSON 会让它失败。大多数报告的原因都是这个。先尽量备份,然后修复预设;见 WLED 预设不保存或错误 12 和备份 WLED。做了恢复出厂设置的人修好了问题,也是同一个原因:重置清掉了坏文件。
  • 那个地址上的东西不是 WLED,或者 WLED 返回了错误页面,比如它正在重启。
  • 在 2025.12 之前的 Home Assistant 版本上,固件低于 0.14。

Home Assistant 2026.10 把这条模糊的消息换成了“The device didn’t respond like a WLED device”,指向的是同样这些原因。

快速测试

在浏览器中打开 http://<light-ip>/json 和 http://<light-ip>/presets.json。如果任何一个打不开,或者看起来不像干净的 JSON,Home Assistant 也会遇到困难。

WLED 实体不可用

“Unavailable”(不可用)的含义取决于是哪个实体:

  • 全部不可用。 Home Assistant 联系不到灯。检查它在线(打开它的网页界面),以及 IP 没有变(下一节)。
  • 只有 Main light 不可用。 灯现在只有一个分段。Main light 只在有两个或更多分段时存在,回到一个分段时它会以不可用的状态留在实体列表里。如果您经常增删分段,开启 Keep Main Light(见下文)。
  • 分段灯、分段速度、调色板、reverse 或 freeze。 那个分段已经不存在了。Home Assistant 从不自行删除分段实体,请手动清理剩下的。
  • Preset 或 Playlist select。 灯上没有预设,或者没有播放列表。保存一个,它就会出现。

在效果和调色板很多的 ESP8266 灯上,整个设备过去会时不时掉成不可用,因为灯返回的 /json 数据太大,被截断了。Home Assistant 2026.10 改为分别读取效果和调色板,修复了这个问题,同时也修复了另一个问题:损坏的预设文件不再会让整个设备不可用。

WLED 换了 IP 地址

路由器重启或长时间停电后,DHCP 可能给灯分配新地址。接下来发生什么取决于您的版本:

  • 如果发现功能正常,Home Assistant 会注意到新地址并自行更新。从 2026.10 起,它会先确认新地址上设备的 MAC 地址与原来相同,这也修掉了一个 bug:手动改好的地址半小时后被改回去。
  • 如果发现功能看不到灯(不同 VLAN),在 WLED 集成条目上使用 Reconfigure,输入新 IP。如果 MAC 不匹配它会拒绝(“MAC address does not match”),这是安全检查,不是故障。

长久的解决办法是在路由器里为每盏 WLED 灯做 DHCP 保留。在 WLED 的 WiFi 设置里设静态 IP 也行,但保留更容易管理。

仅 2025.12

Home Assistant 2025.12.0 到 2025.12.4 在 MAC 相同但大小写不同时可能报告 MAC 不匹配。2025.12.5 修复了它。如果您卡在这个错误上,先更新。

预设或播放列表不显示

  • 新预设没有出现在 select 里。 Home Assistant 2025.11 之前预设列表只读取一次,所以新预设需要重新加载集成。较新的版本在灯报告预设有变化时会更新它。
  • Playlist select 不可用。 灯上没有播放列表。在 WLED 里创建一个(见 WLED 播放列表)。
  • 改动灯之后 select 显示“unknown”。 这是 WLED 的行为,不是 Home Assistant 的。只要您改了颜色、效果或亮度,灯就不再“处于预设 3”,于是 WLED 报告没有活动预设,Home Assistant 显示 unknown。这是正常的。

要在自动化里使用预设,对预设 select 调用 select.select_option,传入预设名称。

分段作为实体

第一个之后的每个 WLED 分段在 Home Assistant 里都成为一个独立的灯实体,名为“Segment 1”、“Segment 2”,依此类推。集成不使用您在 WLED 里给分段起的名字。

  • 实体太多? 禁用您不用的分段灯。
  • 删掉中间一个分段后实体挂到了错误的分段上。 Home Assistant 2026.10 已修复。在更早的版本上,更改分段后重新加载集成。
  • Keep Main Light。 在集成的选项里,“Add ‘Main’ control even with single LED segment”让 Main light 始终存在。开启后,分段灯只控制自己的分段,电源和整体亮度在 Main light 上。如果自动化会增删分段,就开启它。

WLED 分段详解介绍了 WLED 这一侧的分段是什么。

从 Home Assistant 设置的颜色或白光不对

集成只设置分段的主色。2026.10 之前,在有暖白和冷白的灯带(RGB 加 CCT)上,它无法独立设置颜色和色温。WLED 自己的文档也指出 Home Assistant 不适用于配置了 CCT 的设置或白平衡校正,并建议在 LED 设置里开启 Calculate CCT from RGB。Home Assistant 2026.10 修复了 RGB 加 CCT 灯带上色轮跳动和颜色模式错误的问题,所以改设置之前先更新。

从 Home Assistant 更新固件

更新实体提供 WLED 的稳定版(如果您已经在跑测试版,也提供测试版),并每隔几小时检查新版本。会出问题的地方:

  • WLED 16 上更新失败。 WLED 16 有一个安全选项“Only allow update from same network/WiFi”(Config > Security & Updates)。如果 Home Assistant 在不同子网,灯会拒绝。从 2026.10 起 Home Assistant 会显示错误,而不是悄悄失败。关掉这个选项,或者从同一网络更新。
  • 没有更新实体。 从 2026.10 起,Home Assistant 无法识别固件来源的灯(比如自己编译的构建)不会有更新实体,并且只有当发行版有适合您开发板的文件时才会提供更新。
  • 装错了文件(比如以太网开发板失去以太网)。2026.5 已修复,它会挑选与您的开发板匹配的构建。

手动更新见 WLED OTA 更新。

Home Assistant 和其他 App 同时使用

集成与灯保持一个打开的 WebSocket 连接,由灯推送变化。从 Home Assistant 2026.6 起,连接存在时它停止轮询;之前它还每 10 秒轮询一次,这在小开发板上可能让效果卡顿。

WLED 限制 WebSocket 客户端数量(WLED 版本 16 的文档给出 ESP8266 上 3 个、ESP32 上 8 个;再多连一个,最旧的会被断开)。Home Assistant、每个打开的网页界面标签页和一些手机 App 各占一个。如果其中某处的实时更新停了,关掉不需要的网页界面标签页。ESP32 的余量更大。

如果您用 Home Assistant 向 WLED 推流效果(LedFx 或类似 App),灯会进入实时模式并忽略其他一切。见 WLED 卡在实时模式。

改用 MQTT?

WLED 也支持 MQTT,但 WLED 文档推荐原生集成,而且 WLED 不支持 Home Assistant 的 MQTT 自动发现(WLED 多年前就移除了)。只有在有理由时才用 MQTT,然后在 YAML 里手动设置灯。

常见问题

为什么 Home Assistant 对 WLED 显示“Unknown error occurred”? 最常见的是灯上的预设文件损坏,有时是固件低于 0.14,或者设备的回应不像 WLED。Home Assistant 2026.10 显示更清晰的消息。

如何在 Home Assistant 里更改 WLED 的 IP 地址? 打开 WLED 集成条目,选择 Reconfigure,输入新地址。然后设一个 DHCP 保留,避免再次发生。

为什么我的 WLED main light 不可用? 灯只有一个分段。如果您希望它一直存在,在集成选项里开启 Keep Main Light。

Home Assistant 能显示 WLED 的分段名称吗? 不能,分段显示为 Segment 1、Segment 2,依此类推。请在 Home Assistant 里给实体改名。

它支持 WLED 16 吗? 支持。Home Assistant 2026.10 修复了迄今报告的 WLED 16 问题,比如同网络锁定导致的静默更新失败。它还修复了删掉中间一个分段后分段实体混乱的问题。

本文作者

Jamie Conde,在 MeowScript 开发 WLED Max App。WLED 本身是独立的开源项目,我们不是它的一部分。 我们的 iOS 和 Android App WLED Max,一盏灯免费,功能不打折。一次性购买即可添加更多灯。