Home Assistant Matter Hub 跨平台互联配置指南
准备工作:搭建运行环境
在开始配置之前,确保系统满足以下基本要求:
必备条件清单:
- Node.js 16.0 或更高版本
- npm 或 pnpm 包管理器
- 已安装并运行的 Home Assistant 实例
- 支持 Matter 协议的智能家居控制器(如 Apple Home、Alexa 等)
网络环境要求: 确保所有设备位于同一局域网内,这是 Matter 协议正常工作的基础条件。
第一步:项目获取与依赖安装
首先需要获取项目代码并安装必要的依赖包:
git clone https://github.com/home-assistant-matter-hub
cd home-assistant-matter-hub
pnpm install
这里推荐使用 pnpm 作为包管理器,它比 npm 拥有更快的安装速度和更好的磁盘空间利用率。
第二步:环境配置与端口设置
创建一个简单的环境配置文件,设置 Matter Hub 的运行参数:
echo "MATTER_HUB_PORT=8090" > .env
端口 8090 是默认配置,您可以根据需要修改为其他可用端口。
第三步:启动 Matter Hub 服务
运行以下命令启动 Matter Hub:
pnpm start
服务启动后,您将在终端看到类似 "Server started on port 8090" 的提示信息,表示 Matter Hub 已成功运行。
第四步:Apple Home 基础配置
在开始添加 Matter 设备之前,需要确保 Apple Home 的基础设置正确。在家庭设置中,配置好家庭成员权限和网络环境,为后续 Matter 设备添加做好准备。
第五步:连接 Matter 桥接器
现在进入核心步骤——将 Home Assistant Matter Hub 连接到 Apple Home。家庭枢纽与桥接器页面显示了已连接的设备,Matter 桥接器将在此处显示。
第六步:Matter 设备配对流程
当 Apple Home 检测到 Matter 桥接器后,按照以下步骤完成配对:
- 进入配对模式:在桥接器详情页面点击 "Turn On Pairing Mode"
- 输入配对码:系统将生成一个 8 位数的配对码,这是连接 Matter 设备的关键凭证。
第七步:验证与故障排除
完成配对后,需要进行功能验证:
验证项目:
- 在 Apple Home 中查看设备状态是否同步
- 测试设备的控制功能是否正常
- 验证自动化场景是否正常工作
常见问题解决:
- 如果设备未显示,检查网络连接状态
- 如果控制失效,重新启动 Matter Hub 服务
- 如果状态不同步,确认 Home Assistant 实体配置
高级配置技巧
多桥接器管理
如果您有多个 Matter 桥接器,可以在 "Home Hubs & Bridges" 页面统一管理,确保每个桥接器都能正常连接和使用。

