常见问题解答

这是一个由社区整理的关于 Home Assistant 安装、设置和使用的常见问题（FAQ）列表。如果您想了解某个术语的详细信息，请查看术语表。

Home Assistant

404 客户端错误：未找到 (’没有这样的镜像：homeassistant/…)

这个错误表示该镜像，无论是用于更新 Home Assistant，还是安装或更新插件，都无法被拉取到您的系统。这通常是由于没有足够的空间来下载镜像。首先需要检查的是系统上的可用空间。

请注意，如果您将操作系统作为虚拟机运行；默认的虚拟机镜像只有大约 6GB。许多虚拟机用户会遇到这个问题，因为他们没有分配足够的存储空间。推荐的最小大小是 32GB。

您需要检查您自己的系统，确定空间的去向。在 SSH 插件控制台中使用 df -h，您可以快速检查是否有可用空间。

如果有大量可用空间，那么您可能需要检查是否存在网络问题，导致无法下载镜像。

为什么当我点击附加组件的启动按钮时，它会闪烁红色？

如果您正在寻找更多关于无法启动或安装的附加组件的信息，请在用户界面中导航到设置 > 附加组件 > 系统并查看日志。

这个页面上的日志与您在自定义 CLI 中使用 su logs 时看到的日志是相同的。

我正在尝试在主机或SD卡上查找我的文件。它们在哪里？

在Home Assistant OS安装中，您的文件位于数据分区内的/mnt/data/supervisor/。在SD卡上，它是一个标记为hassos-data的EXT4分区。

在Supervised安装中，它们位于/usr/share/hassio/。

我需要保持USB闪存盘连接以使用Wi-Fi吗？

不需要。USB “CONFIG” 闪存盘仅用于将网络配置文件导入到 /etc/NetworkManager/system-connections/，可以拔除。

树莓派 4 的 USB 启动是否支持？

Home Assistant 提供了一个数据磁盘功能，可以将所有数据卸载到附加的 USB 硬盘上。SD 卡仍然在使用，但仅用于支持 Home Assistant 操作系统。了解更多关于数据磁盘功能的信息。

从 USB 启动

由于 USB 和 USB 大容量存储设备类的复杂性，从 USB 设备启动是非常细致的。当从 USB 驱动器启动时，此过程必须多次完成（固件/引导加载程序和操作系统），并且在这些阶段中的某一个期间，未能完成的可能性很高。

也就是说，完全从 USB 驱动器（SSD 或任何其他 USB 大容量存储设备）启动 Home Assistant OS 在某些 USB 设备上是可行的。已知能与树莓派操作系统一起工作的 USB 设备（请查看树莓派论坛）更有可能与 Home Assistant OS 一起工作。然而，由于 Home Assistant OS 在启动链中还包含 U-Boot，因此某些已知与树莓派操作系统兼容的设备却不与 Home Assistant OS 兼容。找到正确的硬件组合可能需要一些实验。

树莓派 4（8GB RAM）是否受支持？

树莓派 4（8GB RAM）在使用 32 位和 64 位镜像的 Home Assistant OS 5.5 及更高版本中是受支持的。目前，64 位是经过更好测试的选项。

使用

依赖

Home Assistant 使用的依赖项存储在配置文件夹目录的 deps 文件夹中。在升级后，依赖项也会被升级。

依赖问题

几乎所有的集成都有外部依赖，以便与您的设备和服务进行通信。有时 Home Assistant 无法安装必要的依赖。如果出现这种情况，应该会在 home-assistant.log 中显示出来。

第一步是尝试重新启动 Home Assistant，看看问题是否仍然存在。如果问题依旧，请查看日志以了解错误是什么。如果您无法解决，请报告它，以便我们可以调查发生了什么情况。

前端表现异常

关闭窗口或标签页，并清除缓存。前端正在 aggressively 缓存，清除缓存确保在您下次访问时前端会重新加载。

升级后，您的浏览器登录卡住

升级到新版本后，您可能会注意到浏览器在“加载数据”登录屏幕上卡住。关闭窗口/标签页，进入浏览器设置并删除您网址的所有 cookies。然后您可以重新登录，应该可以正常工作。

Android Chrome:

chrome -> 设置 -> 网站设置 -> 存储 -> 搜索您的 Home Assistant 的网址 -> “清除与重置”

发现字符 ’ ’ 不能作为任何标记的开始

此错误意味着您在某个 YAML 配置文件中使用了制表符而不是两个空格。请将制表符替换为空格。

连接错误

在运行 Home Assistant 时，您可能会遇到通知您连接问题的回溯。例如。

ConnectionRefusedError: [Errno 111] 连接被拒绝

这很可能不是一个bug，而是服务/守护进程本身的问题。首先检查您的网络（DNS、DHCP、上行链路等），确保 Home Assistant 和服务配置正确。请记住，网络服务可能会出现故障。

安装

Home Assistant与Home Assistant Core

Home Assistant Core 是一个Python程序，简单来说。它可以在各种操作系统上运行，并提供跟踪、控制和自动化设备的能力。当人们谈论Home Assistant Core时，他们通常指的是一种独立的安装方法。

Home Assistant 是Home Assistant Core和工具的结合，这使得在树莓派和其他平台上轻松运行它成为可能，无需先设置操作系统。 Home Assistant是一种一体化解决方案，并具有可以通过Home Assistant前端使用的管理用户界面。这个界面在Home Assistant Core的设置中不存在。

请注意，附加组件仅在常规Home Assistant安装中可用。

distutils.errors.DistutilsOptionError

导致 distutils.errors.DistutilsOptionError: 必须提供 home 或 prefix/exec-prefix 其中之一——不能同时提供 的问题是一个已知问题，如果您是在 Mac 上使用 Homebrew 安装 Python。请按照这些说明来解决它。

pip3: 命令未找到

此工具应该是作为Python 3安装的一部分被安装的。通过运行 python3 --version 来检查是否安装了Python 3。如果未安装，请在这里下载。

如果您能够成功运行 python3 --version 但无法运行 pip3，请通过运行以下命令安装Home Assistant：

python3 -m pip install homeassistant==2025.3.4

在Debian系统上，您也可以通过 sudo apt-get install python3 安装python3，并通过 sudo apt-get install python3-pip 安装pip3。

如果在安装过程中遇到错误，请检查是否已安装所有必要的先决条件包，包括 python3-dev、libffi-dev 和 libssl-dev。在基于Debian的系统上，您可以通过 apt-get 安装这些包：

sudo apt-get install python3-dev libffi-dev libssl-dev

未找到 libyaml 或编译器错误

在 Debian 系统中，通过 sudo apt-get install python3-yaml 安装 Python 3 YAML 库。

没有名为 pip 的模块

Pip 应该与最新的 Python 3 一起捆绑，但某些发行版省略了它。如果您无法运行 python3 -m pip --version，您可以通过下载安装程序并使用 Python 3 运行它来安装 pip：

python3 get-pip.py

常见

发布

Home Assistant 的新版本将在每个月的第一个星期三发布。确切的日期可以在 Home Assistant Developers 网站的即将举行的活动日历中查看。

我们历史上所有发布及其公告博客文章的列表可以在这里找到。

发布计划的最后一周主要专注于Beta测试。参与Beta测试的用户可以在 beta release notes 下查看更新日志，并在 Home Assistant 的 Discord 服务器中的 #beta 频道获得帮助。测试人员也被鼓励在 GitHub 上报告问题。

文档

文档工具

你为什么不使用工具X来制作文档？因为当前的解决方案对我们有效，我们没有看到使用单独发布平台的额外价值。

缺失的文档

Home Assistant 是一个快速发展的开源项目。这意味着官方文档偶尔不会 100% 最新或完整。由于这是一个开源志愿者项目，我们鼓励任何发现文档有缺口的人在底部点击 EDIT 链接，提交他们认为有用的任何更正或增强。关于如何贡献文档的逐步指南可以在这里找到。

在缺乏信息的情况下，许多用户发现查看他人的配置可以帮助他们找到在自己配置中想要实现的示例。找到这些配置的最简单方法是通过这个 GitHub 搜索。

配置

你为什么使用YAML作为配置文件？

而不是使用JSON或XML作为配置文件，因为YAML可以手动编写，你不必担心逗号或标签，而且它是JSON的超集。

我的集成未显示

当集成未显示时，可能有多种不同的情况。在尝试以下步骤之前，请确保查看 home-assistant.log 文件，查看是否有与您尝试设置的集成相关的任何错误。

如果您的配置文件中有错误条目，您可以使用 CLI 脚本检查您的配置，每种安装类型在 common-tasks 中都有其自己的部分：

这个实体没有唯一ID吗？

如果您尝试访问 Home Assistant 中实体的配置对话框，您可能会看到此消息：

没有唯一ID的弹出窗口截图

这意味着这个实体没有唯一的识别，例如，序列号或其他保证是静态且永不更改的标识符。因此，允许您通过用户界面更改各种设置（例如实体ID、图标、友好名称等）的正常编辑过程在这里不可用。

通常，当您使用 YAML 手动创建实体时会看到此情况，但如果提供此实体的集成无法确定唯一ID，也可能会出现这种情况。然而，这并不是错误，只是您所使用的集成的限制。一些选定的集成（例如 template 和 mqtt）允许用户定义唯一ID。

用于哪里？

唯一ID：

仅在 Home Assistant 内部使用。

实体ID：

具有唯一ID的实体：实体ID仅用作引用，例如，在自动化或仪表板中。
没有唯一ID的实体：实体ID充当不存在的唯一ID的替代，并作为引用，例如，在自动化或仪表板中。

可以更改吗？

唯一ID：

不可以。它是一个静态标识符。

实体ID：

具有唯一ID的实体：实体ID可以自由调整（只要遵循格式 <domain>.<id> 且不会导致您 Home Assistant 中出现重复）。请记住，如果您更改实体ID，您还需要更新引用，例如在自动化和仪表板中。
没有唯一ID的实体：实体ID被视为固定的静态标识符，无法更改。

如果您的实体没有唯一ID，因此无法通过 UI 更改，还有一些手动定制选项，可以直接通过 YAML 文件进行。

如果您想了解更多关于唯一ID的信息，请访问这个开发者文档页面。