Home Assistant OS 刷写完整步骤

准备工作

1. 下载对应硬件的 Home Assistant OS 镜像：从官方 installation 页面选择你的硬件型号（树莓派 3/4/5、ODroid、x86-64 等）
2. 下载 BalenaEtcher（推荐）或 Rufus 等烧录工具
3. 一张 ≥ 32GB 的 SD 卡（树莓派方案），或空白硬盘（x86 方案）
4. 网线（首次配置必须有线连接，不支持 Wi-Fi 首次配网）
5. 路由器 DHCP 开启（Home Assistant OS 通过 DHCP 获取 IP）

用 BalenaEtcher 刷写

BalenaEtcher 是最省心的烧录工具，支持 Windows / macOS / Linux：

1. 打开 Etcher，点击 Flash from file，选择下载好的 .img.xz 镜像文件（Etcher 自动解压）
2. 点击 Select target，选择你的 SD 卡或硬盘。注意确认别选错了硬盘——Etcher 会完全擦除目标介质
3. 点击 Flash，等待烧录完成

整个过程大约 5~15 分钟。烧录完成后可以安全移除介质。

首次开机

1. 把 SD 卡插入树莓派（或硬盘接入 x86 主机）
2. 插网线、插电源
3. 等待 1~3 分钟——首次开机需要扩展文件系统、初始化系统分区，期间网卡灯可能会闪烁

浏览器访问

Home Assistant OS 启动后会广播一个 mDNS 名称：

• 默认地址：http://homeassistant.local:8123
• 如果上面打不开，去路由器后台找新分配的 IP 地址（端口 8123）

第一次打开会进入 Onboarding 向导。

可选：无路由器 / 想用固定 IP

如果你想提前设置 Wi-Fi 或固定 IP，可以在刷写完成后不插电源，先在 SD 卡的 CONFIG 分区创建配置文件：

设置 Wi-Fi（CONFIG/network/network.txt）：

ssid="你的 Wi-Fi 名称"
psk="你的 Wi-Fi 密码"

设置静态 IP（CONFIG/network/my-network，用 YAML 格式）：

version: 1
network:
  - type: static
    ipv4:
      address: 192.168.1.100
      netmask: 24
      gateway: 192.168.1.1

常见问题

找不到 homeassistant.local

• Mac：Safari 对 mDNS 支持好，直接访问 http://homeassistant.local:8123
• Windows：打开 cmd，执行 ping homeassistant.local 看能否解析；不能解析就去路由器后台找 IP
• Linux：avahi-browse -rt _home-assistant._tcp 可以扫到

路由器找不到设备

确认网线插好了，等 3 分钟以上。如果还不行，拔了电源等 10 秒再插。Home Assistant OS 首次启动较慢。

想用 SSD 代替 SD 卡

树莓派 4/5 支持 USB 启动，可以把 Home Assistant OS 刷到 SSD 上再从 USB 启动。性能和寿命都比 SD 卡好很多。树莓派 5 默认支持，4 需要先设置一次 USB 启动模式。