企业官网建设流程全解析

Homebridge 入门教程：把家里的非 HomeKit 设备接入 HomeKit 的完整步骤

【免费下载链接】homebridgeHomeKit support for the impatient.项目地址: https://gitcode.com/gh_mirrors/ho/homebridge

家里的小米插座、TP-Link 灯泡、三星电视不支持 Apple HomeKit 认证，却已经能连网。Homebridge 是跑在局域网里的 Node.js 中间件：它模拟 HomeKit 协议，用社区插件把这些第三方设备桥接进来，让家庭 App 和 Siri 直接指挥它们。本教程以「装一台小米插座并让 Siri 开关它」为主线，走完 安装 → 配置 → 语音控制 的闭环。

为它选一个长期运行的部署方式

先定运行环境。Homebridge 需要一个常驻进程：承载机器一旦关机，家庭 App 里的设备立刻失联。按现有条件三选一即可。

Docker 一行启动命令

-v把配置挂到宿主机的~/.homebridge，--net=host让容器直接暴露端口给局域网，省去端口映射。

docker run -d --name hb --net=host -e TZ=Asia/Shanghai -v ~/.homebridge:/homebridge oznu/homebridge:latest

验证：docker logs -f查看该容器输出，出现 Web 界面启动提示且无红色报错即部署成功。

安装 Homebridge 并生成 config.json

顺带说清它是什么：Homebridge 本体不含任何设备驱动，只负责加载homebridge-前缀的插件包，把插件提供的配件发布成 HomeKit 配件。npm 上这类插件已超过 2000 个，小米、TP-Link、三星等品牌都有对应实现。它要求 Node.js 22 或 24（package.json的 engines 字段为^22 || ^24），先确认版本再装。

sudo npm install -g homebridge homebridge-config-ui-x

首次运行会在~/.homebridge/config.json生成配置，关键字段如下片段：

{ "bridge": { "name": "Homebridge", "username": "CC:22:3D:E3:CE:30", "port": 51826, "pin": "031-45-154" }, // 其余字段省略 }

config.json 关键字段逐项说明

• bridge.name：家庭 App 里显示的桥接器名称。
• bridge.username：形如 MAC 的唯一标识，用于区分不同桥接器，改动后需重新配对。
• bridge.port：HAP 服务端口，默认 51826。
• bridge.pin：扫码添加后若提示输入配对码，就填它。

验证：运行homebridge，日志出现 Web 界面启动提示（config-ui-x 默认端口 8581）且无红色报错即成功。

你可能遇到：config.json用严格 JSON 解析，#、//注释都会让进程启动失败并提示读取配置出错。加字段前先去掉所有注释。

安装小米插座插件并写入平台配置

到 npm 搜索homebridge-前缀或homebridge-plugin关键词可定位设备插件；以小米插座为例装一个带前缀的插件，具体型号支持列表以插件仓库 README 为准。

sudo npm install -g homebridge-mi-smart-plug

插件配置里哪些字段要填

在config.json的platforms数组追加一个条目：

"platforms": [ { "platform": "MiSmartPlug", "name": "小米设备", "devices": [ { "name": "客厅插座", "ip": "192.168.1.100", "token": "设备 token" } ] } ]

platform取插件导出的平台名，name是日志里显示的分组名；devices里的ip、token等设备专属字段由插件决定，以所选插件 README 为准。

验证：重启后日志出现该插件的加载行，并列出「客厅插座」这个配件即配置成功。

你可能遇到：装完多个插件后某台设备状态错乱，多是两个插件声明了同名平台或抢占了同一设备。先只保留一个相关插件，逐个排除冲突源；仍无法定位时到插件仓库提 issue，并附上homebridge -D的完整日志。

把桥接器添加到家庭 App 并用 Siri 控制

打开 iOS 家庭 App → 右上角加号 → 添加配件 → 扫描 Homebridge 日志或 Web 界面里的二维码；若要求输入，填bridge.pin。桥接器还没有任何配件时，可能提示「需要额外设置（Additional Set-up Required）」，这是正常现象，后续装插件加设备会自动出现，无需重新配对（摄像头、电视等独立配件除外）。

给设备起名避免 Siri 抢占

Siri 几乎总是优先走它的默认话术：设备叫「收音机」，说「打开收音机」多半触发系统电台；叫「电视」可能唤起系统电视 App。改用「场景 + 设备类型」，如「客厅插座」「卧室灯1」「卧室灯2」，既避开抢占，也方便批量同类设备。

验证：对 Siri 说「打开客厅插座」，设备真被开关，闭环完成。

你可能遇到：

• 家庭 App 搜不到桥接器：换一下 mDNS 广播实现，或给 iPhone 开关一次飞行模式清 DNS 缓存——旧缓存会让设备发现失效。
• 添加失败或无响应：先确认 iPhone 与 Homebridge 在同一局域网且能互相连通；设备尽量接 5GHz 频段——2.4GHz 在家庭环境同频干扰源更多，设备响应延迟通常更高。
• 提示「配件已添加」：可重置配对。删除~/.homebridge/persist会清除已保存的 HomeKit 配对，所有设备需在家庭 App 重新扫码添加；config.json不受影响，操作前先备份该目录。

设备超过 150 台时用子桥接器扩容

单个桥接器最多暴露 150 个配件，这是 HomeKit 的协议上限，不是它的 bug。超了就拆成多个独立桥接器，各配各的配对码，分别加进家庭 App。

子桥接器与多实例的区别

• 子桥接器：同一进程内，给某个插件的platforms条目加_bridge块，它会 fork 出独立进程、独立配对。
• 多实例：跑多个 Homebridge 进程，各自用-U指向独立存储目录。

{ "platform": "MiSmartPlug", "name": "小米设备", "_bridge": { "name": "小米桥", "username": "AA:BB:CC:DD:EE:01" } }

验证：日志出现新的桥接器在独立端口对外广告，家庭 App 里它成为可单独添加的配件；原桥接器的配件数不再逼近 150。

你可能遇到：_bridge.username不能与主桥或其他子桥重复，重复会导致其中一个启动失败；多实例时config.json与persist要隔离到各自目录，否则两个进程会争抢同一份状态。

下一步

家里设备型号没有现成插件时，可以照着 Homebridge 插件开发文档写一个自己的平台插件，起步用官方插件模板仓库；卡住的地方到官方 Discord 社区提问，附上homebridge -D的完整调试日志通常能更快定位问题。

【免费下载链接】homebridgeHomeKit support for the impatient.项目地址: https://gitcode.com/gh_mirrors/ho/homebridge