May 09, 2025

使用 Home Assistant 将米家设备接入 HomeKit 教程

Siri，关灯~

本教程帮助你把常用的米家设备都接入 HomeKit，这样就可以通过 Siri 来控制住处中的智能设备。

具体原理是：使用树莓派安装 Home Assistant，通过 Home Assistant 中的小米官方集成连接米家设备。通过 Home Assistant 中的 HomeKit Bridge 集成，将米家设备桥接到 Apple HomeKit。这样就可以通过 Apple 的“家庭”应用和 Siri 来控制这些设备，即使它们不支持 HomeKit。

1. 安装 Home Assistant
2. 安装与配置 Home Assistant 社区商店 (HACS)
- 2.1 安装 HACS
- 2.2 配置 HACS
3.将米家设备接入 Home Assistant
- 3.1 安装 Xiaomi Home (米家官方) 集成
- 3.2 配置 Xiaomi Home
4. 桥接米家设备到 HomeKit
5.常见问题

我的树莓派配置

Raspberry Pi 5 4gb
OS: Raspberry Pi OS Lite
Kernel: Linux 6.12.20+rpt-rpi-2712 #1 SMP PREEMPT Debian 1:6.12.20-1+rpt1~bpo12+1 (2025-03-19) aarch64 GNU/Linux

1. 安装 Home Assistant

Home Assistant 支持多种安装方式，大致有三种方法：

安装 Home Assistant OS 操作系统
通过 Docker 容器安装
直接安装 Home Assistant Core（逐步弃用，从 Home Assistant 2025.6 版本开始，此安装方式将进入为期六个月的弃用期。）

Home Assistant 官方已提出计划逐步停止对 Home Assistant Core 安装方式的官方支持。建议采用第一种或者第二种方法。

为了便于管理，我选择使用 Docker Compose 来安装 Home Assistant。参考官方教程，docker-compose.yml 如下：

~/docker/homeassistant/docker-compose.yml

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

安装完成后，通过浏览器访问树莓派的 IP 地址加 8123 端口 (例如 http://树莓派IP:8123)。首次访问会进入 Home Assistant 初始化向导，按照提示设置管理员账户和密码。

2. 安装与配置 Home Assistant 社区商店

2.1 安装 HACS

配置完 Home Assistant 后，我们需要安装 HACS（Home Assistant Community Store）。你可以将其理解为 Home Assistant 的应用商店，通过 HACS 我们能够安装第三方集成来增强 Home Assistant 的功能。后续我们需要通过 HACS 来安装小米官方的 Home Assistant 集成。

参考 HACS安装指南，我们需要进入容器内部执行安装脚本。

docker exec -it homeassistant bash
wget -O - https://get.hacs.xyz | bash -

安装成功后，退出容器，然后重启容器。这一步骤很重要，配置HACS前必须重启Home Assistant。

~/docker/homeassistant/

exit
docker compose restart

2.2 配置 HACS

接下来我们需要初始化 HACS，你可以参考此教程或按照下图步骤配置。注意，你需要提前注册一个 Github 账号。

在“设置”中打开“设备与服务”

点击“添加集成”，搜索并选择“HACS”

根据指引逐步操作，打开提示中的网址，登录 GitHub，输入授权码。

看到下图界面，就说明 HACS 已经安装成功了。

指派设备可以先选“跳过并完成”。

3. 将米家设备接入 HomeAssistant

3.1 安装 Home Assistant 米家官方集成

小米在2024年年底推出了官方的 Home Assistant 集成 (Xiaomi Home)。经过多个版本迭代，目前已趋于稳定可用。这意味着我们多了一个官方选择，而不必像以往主要依赖社区维护的 “Xiaomi Miot Auto” 集成。当然，你依然可以选择使用“Xiaomi Miot Auto”集成，对于某些特定设备或追求稳定性的场景，它可能仍有优势。你可以参考我写的另一篇教程：https://wulu.zone/posts/mi-iot-homekit

接下来，我们安装米家官方集成以将米家设备接入HomeAssistant。

进入 HACS 页面，找到“Xiaomi Home”。

点“下载”，然后确认下载。

同样地，安装完集成之后需要重启 HomeAssistant。

~/docker/homeassistant/

docker compose restart

3.2 配置 Xiaomi Home

接下来，我们配置 Xiaomi Home 将米家设备接入 Home Assistant。注意，配置 Xiaomi Home 前需要重启 HomeAssistant。

点击“设置”，选择“设备与服务”

点击“添加集成”，搜索并选择“Xiaomi Home”

登录小米账号以获取设备信息。

在登录认证过程中，如果遇到类似下图的错误提示，通常是因为集成默认使用 homeassistant.local:8123作为OAuth2 认证跳转地址。你可以通过修改路由器或者本地 host，将 homeassistant.local 指向你安装了 Home Assistant 的设备。也可以直接在地址栏修改地址，将homeassistant.local改为对应设备的 IP, 然后刷新网页完成认证。

认证成功后，该页面会自动关闭跳转回 Home Assistant，之后按照指引完成剩余的设备添加步骤即可。