WLED 接入 Apple Home 和 HomeKit:目前可行的方法
WLED 没有内置 HomeKit 或 Matter 支持。这里列出了把 WLED 灯接入家庭 App 的每一种真实可行的方法(Home Assistant、Homebridge、Matter 桥接),以及每种方法能做什么、不能做什么。
**快速回答:**WLED 自己无法加入 Apple Home。到 16.0.1 为止,没有任何 WLED 版本支持 HomeKit 或 Matter。要把 WLED 灯接入家庭 App(Apple Home),您需要在一台常开设备上运行桥接:Home Assistant 加 HomeKit Bridge、装有 WLED 插件的 Homebridge,或者一个 Matter 桥接。如果您只想用 Siri,快捷指令 App 可以直接和 WLED 通信,完全不需要桥接。
不管选哪种桥接,Apple Home 都只能理解一盏基础的灯:开关、亮度、颜色,在大多数桥接上还有色温。家庭 App 本身没有效果控制。大多数桥接不传递效果和调色板,不过有一个 Homebridge 插件可以把选定的效果列成电视输入源那样的列表。预设则以开关、插座、灯或电视输入源的形式出现,取决于桥接。
为什么 WLED 没有原生接入 Apple Home
多年来一直有人提出这个需求。WLED GitHub 上的 Matter 请求(issue #2871)仍然处于打开状态,并标记为“help wanted”。维护者的解释很务实:Matter 需要比任何 WLED 发行版所用版本更新的 Espressif 框架(开发分支已在 2026 年 7 月切换过去,但还没有发行版用上它),而 ESP8266 这类老芯片没有足够的内存。2026 年 3 月有人提交了一个在 ESP32-S3 上以 usermod 形式加入 Matter 的概念验证,后来未经合并就关闭了。
所以就目前来说,对于您已经拥有的每一块开发板,桥接是唯一的路。
Apple Home 能显示什么
| 在家庭 App 中 | 能通过桥接实现吗? |
|---|---|
| 开和关 | 可以 |
| 亮度 | 可以 |
| 颜色 | 可以 |
| 色温(暖白到冷白) | 大多数桥接可以,前提是灯带有白光通道,或者 WLED 报告色温 |
| 效果(Fireworks、Twinkle 等) | 不能作为效果;有一个 Homebridge 插件可以把选定的效果列成电视输入源 |
| 调色板 | 不能 |
| 预设 | 以开关或插座的形式,取决于桥接(见下文) |
| 分段 | 在部分桥接上作为独立的灯 |
各处通用的实用技巧是一样的:先在 WLED 里把想要的效果做成预设,再把这个预设作为开关带进家庭 App。“Movie”就成了家庭场景或自动化里的一个按钮。
选一条路线
| 路线 | 运行在 | 家庭 App 中的预设 | 分段 | 工作量 |
|---|---|---|---|---|
| Home Assistant + HomeKit Bridge | 您的 Home Assistant | 可以,显示为一个“电源插排”,每个预设一个插座 | 可以,每个分段一盏灯 | 如果已经在用 Home Assistant,很低 |
| Homebridge + WLED 插件 | Raspberry Pi、NAS 或常开电脑 | 可以,显示为开关、灯或电视输入源(取决于插件) | 部分插件支持 | 中等 |
| Matter 桥接 | Home Assistant 应用或 Docker | 基本不行,只有灯 | 通过 Home Assistant | 中等 |
| 快捷指令和 Siri,不用桥接 | 您的 iPhone | 作为快捷指令,不在家庭 App 里 | 每条快捷指令单独设 | 低 |
如果您已经在用 Home Assistant,就从它开始。如果没有,Homebridge 更轻量,只做这一件事。
Home Assistant 加 HomeKit Bridge
这是最完整的路线,因为 Home Assistant 对 WLED 已经了解很多。
-
在 Home Assistant 中添加 WLED 集成。它通常能自己找到您的灯(需要 WLED 0.14.0 或更新版本)。如果找不到,我们的 Home Assistant 问题修复指南可以帮您。
-
添加 HomeKit Bridge 集成:Settings›Devices & services›Add integration,搜索 HomeKit Bridge。它列在 Apple 下面。
Home Assistant 2026.10 
选择 HomeKit Bridge。HomeKit Device 是反方向的(把 HomeKit 设备接入 Home Assistant)。 -
限制它共享的内容。在桥接的选项里,包含 light 域(想要预设的话再加上 select),然后只挑选您想要的 WLED 实体。否则您家里的每个传感器和开关都会出现在家庭 App 里。
Home Assistant 2026.10 
设置过程中,清除预选的域,只保留 Light 和 Select。 Home Assistant 2026.10 
然后打开桥接的 Configure,选择 include 模式,挑选 WLED 灯和它的 Preset 选择项。 -
在 Home Assistant 中打开配对通知,然后在家庭 App 里点按 +、添加配件,扫描二维码。
Home Assistant 2026.10 
配对通知,在侧边栏的 Notifications 下。这张截图来自一个临时的测试安装,所以这个代码没法用。
家庭 App 中您会得到:
- 每盏 WLED 灯一盏灯,带颜色。如果这盏灯有多个分段,Home Assistant 会创建一盏 Main 灯(只有电源和整体亮度,没有颜色),再加上每个分段一盏灯。共享 Main 灯用于开、关和调光;如果想在家庭 App 里设置颜色,再共享第一个分段的灯。
- 颜色和亮度,以及色温(如果灯支持)。
- 预设和播放列表以 select 实体的形式过来,HomeKit Bridge 把它们显示为一个电源插排,每个选项一个插座。共享预设 select,您就能在家庭 App 里点“Christmas”,或者把它用在场景里。
一个 HomeKit 桥接最多容纳 150 个配件。如果 WLED 灯、分段和 select 很多,专门为灯再开一个桥接实例会更清爽。
带 WLED 插件的 Homebridge
Homebridge 是一个小型服务器,专门把非 HomeKit 设备接入 Apple Home。它可以运行在 Raspberry Pi、NAS 或任何常开的电脑上。
-
安装带网页界面的 Homebridge(Homebridge 网站提供系统镜像和安装程序)。
-
在 Plugins 标签页里搜索 WLED,安装下面列出的插件之一。
Homebridge UI 5.29 
绿色盾牌标记的是经过验证的插件。下载箭头可以选择要安装的版本。 -
在插件设置里输入您各盏灯的 IP 地址(先在路由器里为它们做 DHCP 保留,这样地址就不会变)。
homebridge-wled-ws 0.0.25 
homebridge-wled-ws 安装后会直接打开这个表单。预设按名称列出,用逗号分隔。 -
在家庭 App 里,扫描 Homebridge 控制面板上的二维码来添加配件。如果您保留了 Homebridge 在首次保存插件设置时提供的子桥接(默认开启),该插件会有自己的二维码:点按插件卡片上的二维码图标(Connect to HomeKit)。
Homebridge UI 5.29 
子桥接自己的配对码。子桥接需要和主桥接分开添加到家庭 App。

截至 2026 年 10 月,值得关注的插件如下。Homebridge 的“Verified”标记表示 Homebridge 团队按照其准则检查过该插件。
| 插件 | 已验证 | 提供什么 |
|---|---|---|
| homebridge-wled-ws | 是 | 一盏带电源、亮度和颜色的灯;您列出的每个预设一个开关;可选的实时模式开关。只控制主分段 |
| homebridge-simpler-wled | 是 | 电源、亮度和颜色;预设以电视输入源列表的形式呈现;可选为每个分段单独建配件 |
| @ncovercash/homebridge-wled-presets | 是 | 只有预设:每个预设是一盏独立的灯,有开、关和亮度,打开一个会关掉其他的。没有颜色控制。版本 1.1.4,最后更新于 2026 年 4 月 |
| homebridge-simple-wled | 否 | 电源、亮度和颜色;选定的效果或预设以电视输入源列表呈现(二者只能选一个) |
homebridge-wled-ws 列出了它测试过的 WLED 版本(2026 年 10 月时最高到 0.15.4,还没有 16 的);其他插件最多只给出最低版本。把灯升级到新的大版本之前请先查一下。
Matter 桥接
Matter 是更新的智能家居标准,Apple Home 支持 Matter 灯。Matter 桥接把它已经认识的灯作为 Matter 设备提供出去。对 WLED 来说,目前有这几种:
- Home Assistant Matter Hub,作为 Home Assistant 应用(以前叫 add-on)。原项目在 2026 年 1 月停止维护并已归档;RiDDiX 的社区分支是目前仍在维护的那个。
- Matterbridge 加它的 matterbridge-hass 插件,同样建立在 Home Assistant 之上。
- wled-matter-bridge,GitHub 上的一个小型独立项目,它在您的网络上查找 WLED 灯,不经 Home Assistant 直接通过 Matter 提供出去。它运行在 Docker 里。
这三种都能给 Apple Home 一盏有开、关、亮度和颜色的灯。没有一种能传递效果或调色板。其中两个项目提到一个 Apple 的小毛病:家庭 App 会保留设备配对时的名称,之后给灯改名不会同步过去。
如果您同时还在用 Google Home 或 Alexa,Matter 最有意义,因为一个桥接可以服务所有平台。只用 Apple Home 的话,HomeKit Bridge 或 Homebridge 能做同样的事,环节更少。
不用桥接:Siri 和快捷指令
如果您只想说一句“嘿 Siri,电影灯光”,就跳过桥接。快捷指令 App 可以用获取 URL 内容直接向灯的 JSON API 发送命令,例如 {"ps":5} 加载预设 5。我们的快捷指令和 Siri 指南有具体步骤和一张命令表。
问题在于:快捷指令不是家庭配件。它们不会出现在家庭 App、家庭场景或控制中心的家庭控制里,而且只有当您的 iPhone 和灯在同一网络时才能联系到灯。
我们的 App WLED Max 也属于这一类。在 iOS 上它提供 Siri 短语和快捷指令操作(开关、亮度、颜色、预设、效果),不需要输入任何 URL,但它不会把灯放进家庭 App。
自动化需要家庭中枢
Apple Home 需要一个家庭中枢(Apple TV 或 HomePod)来运行自动化,以及在您外出时控制配件。没有中枢的话,桥接过来的 WLED 灯在家里用手机能控制,但“日落时打开门廊灯”不会运行。WLED 自己的定时器不需要这些:见日出和日落定时计划。
常见故障
灯在家庭 App 里显示“无响应”。 桥接联系不到灯。通常是路由器重启后灯拿到了新的 IP 地址。给它做个 DHCP 保留,再更新桥接里的地址。
配件太多。 HomeKit Bridge 会共享您包含进去的一切。把范围缩小到 WLED 灯实体,每盏灯再加一个预设 select。
改名后的灯在家庭 App 里还是旧名字。 在家庭 App 里也改一次名。桥接在配对时就定好了名称。
常见问题
WLED 支持 HomeKit 吗? 不原生支持。您需要一个桥接,比如 Home Assistant 的 HomeKit Bridge 或 Homebridge。
WLED 支持 Matter 吗? 到 16.0.1 为止的任何版本都不支持。功能请求仍然开着,Matter 桥接可以填补这个空缺。
我能在家庭 App 里选 WLED 效果吗? 不能作为效果选。把效果保存为 WLED 预设,再把预设暴露为开关或插座;或者用 homebridge-simple-wled,它可以把选定的效果列成电视输入源。
如果我不用 Home Assistant,最简单的方法是什么? 在 Raspberry Pi 上运行 Homebridge,配 homebridge-wled-ws 或 homebridge-simpler-wled。