Apple HomeKit Bridge 接入教程
Apple HomeKit Bridge 集成可以把 Home Assistant 里的设备桥接到苹果「家庭（HomeKit）」中，让你在 iPhone / iPad 的「家庭」App 里控制 HA 设备。需要特别注意：它桥接的是设备中的某个实体，而不是把一个完整设备整个桥接过去，这一点与小米、美的、海尔等第三方设备的用法不同。本文演示在冬瓜 HAOS 上接入并使用「Apple HomeKit Bridge」集成的完整流程。
| 名称 | OS | Core |
|---|---|---|
| 版本 | 17.0 | 2025.2.1 |
在开始之前，请确认：
- HA 盒子、电脑和待接入设备都处于同一个局域网内（详细网络设置可参考「智能设备网络设置」文档）。
- 准备好一台苹果设备（iPhone 或 iPad）及其「家庭」App，用于扫码添加桥接设备。
重要：本集成桥接的是设备中的某个实体，并非把一个完整设备整体桥接过去，这与小米、美的、海尔等第三方设备的用法不同，请特别留意。
接入步骤（建立 HomeKit Bridge 连接）
Section titled “接入步骤（建立 HomeKit Bridge 连接）”第 1 步：添加集成并搜索 apple
Section titled “第 1 步：添加集成并搜索 apple”依次进入 设置 → 设备与服务 → 集成 → 添加集成，搜索 apple。
第 2 步：选择 HomeKit Bridge
Section titled “第 2 步：选择 HomeKit Bridge”点击 Apple，再点击 HomeKit Bridge。
第 3 步：提交两次
Section titled “第 3 步：提交两次”连续点击 提交 两次。
第 4 步：关闭弹窗
Section titled “第 4 步：关闭弹窗”点击 X 关闭弹窗。
注意：这里不要点击「跳过并完成」，否则会进入该集成内部。
添加设备到 Apple 家庭
Section titled “添加设备到 Apple 家庭”第 1 步：进入配置并选择包含模式
Section titled “第 1 步：进入配置并选择包含模式”进入 HomeKit Bridge，点击 ⚙ 图标进行配置。在「包含模式」中选择 include；要包含的「域（设备类型）」目前只选择 switch（开关）；如果没有开关，也可以选择 Light（灯），然后点击 提交。
第 2 步：选择要桥接的实体
Section titled “第 2 步：选择要桥接的实体”在实体字段中可以粘贴实体标识符（查询方法见相关文档）或直接选择。建议第一次只添加一个实体以防失误。点击 提交 后，在弹窗中点击 完成。
第 3 步：打开通知菜单
Section titled “第 3 步：打开通知菜单”点击左侧的「通知」菜单。
第 4 步：找到 HomeKit Bridge 二维码
Section titled “第 4 步：找到 HomeKit Bridge 二维码”找到「HomeKit Bridge」二维码。一般情况下第一个桥的名称为 HASS Bridge:21064。
第 5 步：在苹果「家庭」App 中开始添加
Section titled “第 5 步：在苹果「家庭」App 中开始添加”用苹果手机或 iPad 进入「家庭」App，点击右上角的 +，选择 添加或扫描配件。
第 6 步：扫描二维码
Section titled “第 6 步：扫描二维码”用苹果设备扫描屏幕上显示的二维码。
第 7 步：仍然添加
Section titled “第 7 步：仍然添加”点击 仍然添加 按钮。
第 8 步：添加到 Apple 家庭
Section titled “第 8 步：添加到 Apple 家庭”点击 添加到 Apple 家庭。
第 9 步：设置桥接设备位置
Section titled “第 9 步：设置桥接设备位置”在「桥接设备位置」选项中向下拉，可看到 新建房间。建议把房间名称设为 HK桥，后续所有桥接设备都放在此位置，方便管理。
第 10 步：按需完成其余选项
Section titled “第 10 步：按需完成其余选项”后续选项按需自行选择即可。
第 11 步：完成添加
Section titled “第 11 步：完成添加”完成添加，设备会出现在苹果「家庭」中。
创建多个桥接
Section titled “创建多个桥接”建议把不同类型的设备分别建立多个「HomeKit Bridge」便于管理。进入「HomeKit Bridge」，点击 添加条目，再点击 跳过并完成；多个设备类型需要重复此操作。
这样做的优势：
- 误操作不会影响全部设备；
- 方便单独删除某一类型的设备；
- 支持按房间或设备分类管理。
点击需要操作的桥名称后的 ︙ 菜单，选择重命名，在对话框中输入新名称并点击确定。建议在苹果「家庭」中也改为相同名称。
添加失败处理
Section titled “添加失败处理”如果出现无法添加或一直加载的情况，需要删除该「HomeKit Bridge」后，重新「添加条目」。
从家庭中移除桥
Section titled “从家庭中移除桥”依次点击 家庭 → ┄ → 家庭设置 → 家庭中枢与网桥，选择需要删除的桥，再选择 从家庭移除桥接设备。
排除（删除）特定设备
Section titled “排除（删除）特定设备”进入「HomeKit Bridge」，点击需排除设备后的 配置，在「包含模式」中选择 exclude（排除），点击 提交。找到待排除实体后的 ×，稍等片刻，家庭中就会移除该实体。
| 问题 | 解决办法 |
|---|---|
| 建立连接最后一步该点哪里 | 第 4 步点击 X 关闭弹窗，不要点「跳过并完成」，否则会进入集成内部。 |
| 设备无法添加 / 一直加载 | 删除该「HomeKit Bridge」后重新「添加条目」再试。 |
| 一次添加多个实体容易出错 | 第一次建议只添加一个实体，确认无误后再逐步添加。 |
| 想分类管理设备 | 按设备类型分别建立多个「HomeKit Bridge」，并统一放到「HK桥」房间。 |
| 想取消桥接某个实体 | 在对应桥的「配置」中把「包含模式」改为 exclude（排除），提交后点实体后的 × 移除。 |
| 想整体移除某个桥 | 在「家庭 → 家庭设置 → 家庭中枢与网桥」中选择该桥，从家庭移除桥接设备。 |
接入 Apple HomeKit Bridge 的核心流程是：添加 apple 集成 → 选 HomeKit Bridge → 提交两次 → 关闭弹窗建立连接，随后配置包含模式（include + switch/light）→ 选择实体 → 在通知里找二维码 → 用苹果「家庭」App 扫码添加 → 新建「HK桥」房间 → 完成。记住它桥接的是实体而非整机，建议按类型分桥管理，遇到问题可删除重建或用 exclude 排除特定实体。