WLED Apple Home HomeKit Matter iOS 智能家居

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 已经了解很多。

  1. 在 Home Assistant 中添加 WLED 集成。它通常能自己找到您的灯(需要 WLED 0.14.0 或更新版本)。如果找不到,我们的 Home Assistant 问题修复指南可以帮您。

  2. 添加 HomeKit Bridge 集成:Settings›Devices & services›Add integration,搜索 HomeKit Bridge。它列在 Apple 下面。

    Home Assistant 2026.10
    Home Assistant 的 Add integration 对话框,选择 Apple 后标题为 What do you want to add,列出 Apple iCloud、Apple TV、Apple WeatherKit、HomeKit Bridge、HomeKit Device、iBeacon Tracker 和 Apple iTunes
    选择 HomeKit Bridge。HomeKit Device 是反方向的(把 HomeKit 设备接入 Home Assistant)。
  3. 限制它共享的内容。在桥接的选项里,包含 light 域(想要预设的话再加上 select),然后只挑选您想要的 WLED 实体。否则您家里的每个传感器和开关都会出现在家庭 App 里。

    Home Assistant 2026.10
    HomeKit Bridge 设置步骤 Select domains to be included,Domains to include 设为 Light、Select,还有一个 Submit 按钮
    设置过程中,清除预选的域,只保留 Light 和 Select。
    Home Assistant 2026.10
    HomeKit Bridge 选项步骤 Select the entities to be included,选中了两个实体:Porch Lights(灯)和 Preset (Porch Lights)
    然后打开桥接的 Configure,选择 include 模式,挑选 WLED 灯和它的 Preset 选择项。
  4. 在 Home Assistant 中打开配对通知,然后在家庭 App 里点按 +、添加配件,扫描二维码。

    Home Assistant 2026.10
    Home Assistant 通知 HomeKit Pairing:To set up HASS Bridge in the Home App, scan the QR code or enter the following code,附带一个八位代码和一个二维码
    配对通知,在侧边栏的 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 或任何常开的电脑上。

  1. 安装带网页界面的 Homebridge(Homebridge 网站提供系统镜像和安装程序)。

  2. 在 Plugins 标签页里搜索 WLED,安装下面列出的插件之一。

    Homebridge UI 5.29
    Homebridge 的 Plugins 标签页搜索 wled,显示 Homebridge Wled Ws、Homebridge WLED Presets、Homebridge Simpler Wled 和 Homebridge Script2,每个都带版本号和下载按钮
    绿色盾牌标记的是经过验证的插件。下载箭头可以选择要安装的版本。
  3. 在插件设置里输入您各盏灯的 IP 地址(先在路由器里为它们做 DHCP 保留,这样地址就不会变)。

    homebridge-wled-ws 0.0.25
    homebridge-wled-ws 设置,Controllers 部分:Name 为 Porch Lights,IP Address or Hostname 为 192.168.1.50,List of presets 为 Warm White,Christmas,Movie,还有一个未勾选的 Realtime Mode Button 选项
    homebridge-wled-ws 安装后会直接打开这个表单。预设按名称列出,用逗号分隔。
  4. 在家庭 App 里,扫描 Homebridge 控制面板上的二维码来添加配件。如果您保留了 Homebridge 在首次保存插件设置时提供的子桥接(默认开启),该插件会有自己的二维码:点按插件卡片上的二维码图标(Connect to HomeKit)。

    Homebridge UI 5.29
    WLED 插件的 Homebridge 子桥接设置,Enable HAP (Apple Home) 已开启,一个二维码、设置代码和状态 Not Paired,Scan to add to HomeKit
    子桥接自己的配对码。子桥接需要和主桥接分开添加到家庭 App。
Homebridge UI 5.29
Homebridge 的 Accessories 标签页,Default Room:一盏亮度 49% 的 Porch Lights 灯和三个名为 Warm White、Christmas、Movie 的开关,全部关闭
homebridge-wled-ws 交给 Apple Home 的内容:一盏灯,加上您列出的每个预设一个开关。

截至 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。