一、速览：Homebridge 解决什么问题

入门

如果你买了一个智能灯泡，它本身不支持苹果 HomeKit，但你又想让 Siri 帮你开灯关灯，直接买带 HomeKit 认证的设备往往更贵。Homebridge 就是来解决这个「兼容鸿沟」的。

它本质上是一个跑在你家里的小型服务器，用 Node.js（一种 JavaScript 运行环境，可以简单理解为一个能执行代码的服务程序）写成。它会在家里模拟出一个「假的」HomeKit 桥接器，让苹果设备以为那些不兼容的智能设备其实是支持 HomeKit 的。

打个比方：Homebridge 就像一位翻译。智能灯泡只会说「甲语言」，苹果 HomeKit 只会说「乙语言」，二者无法直接沟通。Homebridge 站在中间，把两边的话互相翻译，于是 Siri 就能听懂灯泡的指令了。

Homebridge 是一个免费、非商业、社区驱动的开源项目。它与 Apple、Google、Amazon 没有任何隶属关系，也不是经过认证的付费产品。

它最大的特色是插件机制。社区开发者写了上千个插件，覆盖小米、米家、涂鸦、三星、索尼、LG 等大量品牌。你只需要安装对应的插件，做一点配置，就能把设备接入苹果家庭 App。从 v2 版本开始，Homebridge 还支持 Matter 协议，这意味着接入的设备也能被 Google Home、Amazon Alexa 等平台识别。

二、快速部署：Docker 一条命令跑起来

入门

前置条件：你需要一台能 24 小时开机的设备来运行 Homebridge，可以选择家里的 NAS、树莓派、软路由，或者一台旧电脑。它必须和你的智能设备在同一个局域网里，并且能联网安装软件。

推荐使用 Docker 部署。Docker 是一种把软件打包成「集装箱」的工具，它把 Homebridge 和它需要的所有依赖都装在一个封闭环境里，安装、升级、卸载都不会弄乱系统。如果还没装 Docker，可以先去 Docker 官网下载 Docker Desktop（Windows/Mac）或使用命令行安装（Linux）。

确认 Docker 可用后，执行下面这条命令：

docker run -d \
  --name homebridge \
  --restart=always \
  --network=host \
  -v /homebridge:/homebridge \
  -e TZ=Asia/Shanghai \
  homebridge/homebridge:latest

这条命令做了几件事：

• --name homebridge：给容器起个名字叫 homebridge
• --restart=always：每次设备重启后自动重新运行 Homebridge
• --network=host：让容器直接使用宿主机的网络，这样 Homebridge 才能在局域网中被苹果设备发现
• -v /homebridge:/homebridge：把宿主机的 /homebridge 文件夹映射到容器内，所有配置和插件都保存在这里，删掉容器数据也不会丢
• -e TZ=Asia/Shanghai：设置时区为中国标准时间

注意：如果你用的是 Windows 或 macOS 上的 Docker Desktop，--network=host 可能表现不同。建议在 Linux 服务器、树莓派或 NAS 上部署，体验最顺畅。

启动完成后，打开浏览器访问 http://你的设备IP:8581，就会看到 Homebridge 的 Web 管理界面。默认账号和密码都是 admin，登录后系统会引导你创建管理员账户。

如果浏览器打不开页面，先用 docker logs homebridge 查看容器日志，确认是否启动成功。

三、配置详解：认识 config.json 与核心参数

进阶 · 推荐细读

Homebridge 的所有配置都写在一个叫 config.json 的文件里。用 Docker 部署的话，它就在宿主机的 /homebridge/config.json 路径下。你可以通过 Web 界面右上角的「配置」入口编辑它，也可以直接编辑文件。

一个最小可用的配置长这样：

{
  "bridge": {
    "name": "Homebridge",
    "username": "CC:22:3D:E3:CE:30",
    "port": 51826,
    "pin": "031-45-154"
  },
  "platforms": []
}

这个 bridge 块定义了 Homebridge 主桥接器的「身份证」。当你在苹果家庭 App 里扫码或手动添加配件时，看到的就是这个名字和 PIN 码。可以把它类比为一台虚拟的 HomeKit 中枢设备，所有插件接入的配件都会挂在这台设备下面。

几个关键参数说明：

platforms 数组用来放置插件配置。每个插件都会在它的文档里说明需要在 platforms 中填写什么内容。

从 v2 开始，配置里还可以增加一个 matter 块。加上之后，Homebridge 会额外启动一个 Matter 服务器，让桥接的配件也能被 Google Home、Amazon Alexa 等支持 Matter 的平台发现。每个启用 Matter 的桥接器会生成自己的 Matter 配对码，你可以用不同平台的控制端分别扫码配对，互不影响。

没有添加 matter 块的桥接器行为完全不变，仍然只走 HomeKit 协议。Matter 功能是可选的增强，不是必选项。

在 Web 界面里修改配置后，Homebridge 会自动检测变化并重启服务。配置文件写错格式（比如少一个引号）会导致启动失败，所以保存前建议先用界面里的「配置检查」功能验证 JSON 格式是否正确。

四、功能导览：装插件、接设备、用 Siri 控制

入门

登录 Web 界面后，最常用的入口是「插件」标签页。这里可以搜索、安装、管理 Homebridge 插件。比如你想接入小米系的智能设备，就在搜索框输入 mi，找到社区评分较高的插件，点击安装。

安装插件后，一般需要做两件事：

1. 添加插件配置：在「配置」界面中，把插件要求的配置块填入 platforms 数组
2. 填写设备凭据：很多插件需要你提供设备厂商的账号密码或局域网 IP，具体看插件文档

配置完成后保存，Homebridge 会重启并加载插件。如果一切正常，打开苹果家庭 App，点击「添加配件」，扫描 Homebridge 生成的二维码，然后输入配置里的 PIN 码，就能看到桥接过来的所有设备了。

添加成功后，你就可以这样用：

「嘿 Siri，把客厅的灯打开」「嘿 Siri，把空调调到 26 度」「嘿 Siri，我出门了」——只要插件支持对应设备的能力，这些语音指令就能直接执行。

Homebridge 的 Web 界面还提供了配件状态查看、日志监控、备份恢复等功能。建议在「设置」里开启自动备份，这样换机器或重装时能快速恢复整套配置。

五、常见问题：端口、权限、网络排查

进阶 · 推荐细读

新手在部署和运行阶段最常遇到的几个问题，下面逐一说明解决方法。

端口冲突怎么办？

Homebridge 默认使用 51826（HomeKit 协议端口）和 8581（Web 界面端口）。如果 8581 被其他服务占用，可以在 Docker 命令中改用其他端口映射，例如把宿主机端口换成 8681：

docker run -d \
  --name homebridge \
  --restart=always \
  --network=host \
  -v /homebridge:/homebridge \
  -e TZ=Asia/Shanghai \
  -e HOMEBRIDGE_CONFIG_UI_PORT=8681 \
  homebridge/homebridge:latest

苹果家庭 App 搜不到 Homebridge 怎么办？

这是局域网发现机制的问题。Homebridge 依赖 mDNS（一种局域网设备发现协议），如果路由器开启了「AP 隔离」或「访客网络隔离」，不同设备之间就无法互相发现。检查路由器设置，关闭 AP 隔离，确保手机和 Homebridge 在同一个网段。

插件装好了但不显示设备？

先看日志。Web 界面里的「日志」标签页会输出插件运行时的错误信息。常见原因是插件配置里缺少必填字段、账号密码错误、或者设备固件升级后插件暂不支持。拿日志去插件的 GitHub 或 Discord 社区提问，比盲目调试高效得多。

数据会丢吗？

只要 /homebridge 这个挂载目录不删，所有配置、插件、配对信息都在里面。建议定期备份这个文件夹。Web 界面里也有备份功能，可以把配置打包下载到本地。

遇到无法自己解决的问题，官方 Discord 和 Reddit 社区是很好的求助渠道。描述问题时附上日志截图和配置片段，社区成员会更愿意帮你排查。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「PlayEdu」中文使用教程
• 「twenty」中文使用教程
• 「whoogle-search」中文使用教程