2025.3.4
首页 ▸ 文档 ▸ Configuration ▸

排查您的配置

在配置Home Assistant时，您可能会遇到问题。也许某个集成没有显示或者表现异常。此页面将讨论一些最常见的问题。

在深入讨论常见问题之前，请确保您知道配置目录的位置。Home Assistant在启动时会打印出它正在使用的配置目录。

任何集成或配置选项导致的警告将保存在配置目录中的 home-assistant.log 文件中。此文件在Home Assistant启动时会重置。

我的集成没有显示

当某个集成没有显示时，可能有多种不同的情况。在尝试这些步骤之前，请先检查 home-assistant.log 文件，查看是否有与您尝试设置的集成相关的错误。

如果您的配置文件中有错误条目，可以使用配置检查命令（如下）来帮助识别它们。

配置问题

Home Assistant最常见的问题之一是无效的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 或其他配置文件。

  • Home Assistant提供了一个CLI，允许您查看它如何解析这些文件，每种安装类型在公共任务中都有自己的部分：

  • 配置文件，包括 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 必须是UTF-8编码。如果您看到错误如 'utf-8' codec can't decode byte，请编辑有问题的配置并重新保存为UTF-8。

  • 您可以使用这个在线YAML解析器 或 YAML验证器 来验证您配置的 YAMLYAML 是一种人类可读的数据序列化语言。它用于以结构化格式存储和传输数据。在 Home Assistant 中，YAML 用于配置，例如在 configuration.yaml 或 automations.yaml 文件中。 [Learn more] 结构。

  • 要了解更多关于 YAMLYAML 是一种人类可读的数据序列化语言。它用于以结构化格式存储和传输数据。在 Home Assistant 中，YAML 用于配置，例如在 configuration.yaml 或 automations.yaml 文件中。 [Learn more] 的特性，请阅读 YAML 特性（SaltStack提供的，该示例特定于SaltStack，但很好地解释了YAML问题）。

configuration.yaml 不允许多个部分具有相同的名称。如果您想为一个集成加载多个平台，可以在名称后追加数字或字符串，或者嵌套它们：

sensor:
  - platform: forecast
    ...
  - platform: bitcoin
    ...

另一个常见问题是缺少必需的配置设置。如果是这种情况，集成将会在 home-assistant.log 中报告此问题。您可以查看各种集成页面以获取有关如何设置集成的说明。

有关如何为特定模块定义所需日志级别的说明，请查看logger 集成。

如果您发现任何错误或想要扩展文档，请告诉我们。

依赖问题

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

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

集成问题

某些集成可能在一开始无法正常工作，或在Home Assistant运行一段时间后停止工作。如果发生这种情况，请报告，以便我们查看。

多个文件

如果您使用多个文件进行设置，请确保指向的文件路径正确且文件格式有效。理解不同类型的 !include 以及每个文件的内容应该如何结构至关重要 - 有关将配置拆分为多个文件的各种方法的信息请参见此处。

light: !include devices/lights.yaml
sensor: !include devices/sensors.yaml

lights.yaml 的内容（注意它不包含 light:）：

- platform: hyperion
  host: 192.168.1.98
  ...

sensors.yaml 的内容：

- platform: mqtt
  name: "房间湿度"
  state_topic: "room/humidity"
- platform: mqtt
  name: "门运动"
  state_topic: "door/motion"
  ...

Note

每当您报告一个问题时，请注意我们是志愿者，并没有访问世界上每个设备的权限，也没有无限的时间来解决所有问题。

实体名称

实体名称中有效的字符只有：

  • 小写字母
  • 数字
  • 下划线

实体名称不能以下划线开头或结尾。如果您通过用户界面创建了包含其他字符的实体，Home Assistant会验证该名称。如果您直接在 YAMLYAML 是一种人类可读的数据序列化语言。它用于以结构化格式存储和传输数据。在 Home Assistant 中，YAML 用于配置，例如在 configuration.yaml 或 automations.yaml 文件中。 [Learn more] 文件中更改名称，则Home Assistant可能不会为该实体生成错误。但是，尝试使用该实体将会产生错误（或可能静默失败）。

有关如何更改实体名称的说明，请参见定制实体一节。

调试日志和诊断

在网上报告问题之前，您首先需要集成的调试日志和诊断（如果可用）。提前收集这些信息将确保有人能够以最快的方式帮助解决您的问题。

启用调试日志

要为特定集成启用调试日志，请按照以下步骤操作：

  1. 转到设置 > 设备与服务。

  2. 选择集成卡以打开您要启用调试日志的集成的详细页面。

  3. 在集成详细页面的左侧，选择 启用调试日志。

    • 截图使用MQTT集成作为示例进行说明，并不意味着您需要安装MQTT集成。

    显示启用调试日志按钮的集成详细页面截图 截图显示了集成详细页面上的 启用调试日志 按钮。MQTT集成被用作示例以显示按钮的位置。

  4. 要在日志中查看错误，您需要重现该错误。继续查看禁用调试日志并下载日志。

禁用调试日志并下载日志

启用调试日志后，您理想情况下需要让错误发生。运行您的自动化，改变您的设备或引发错误的任何操作，然后回来禁用调试日志。禁用调试日志与启用一样，但现在按钮显示为 禁用调试日志。禁用后，系统会自动提示您下载日志文件。将其保存到安全的位置以便稍后上传。

下载诊断信息

下载日志后，您还需要下载导致问题的集成的诊断信息。如果集成提供诊断，它将出现在集成配置旁的三个点菜单中。

下载诊断示例 下载诊断的示例。

处理意外重启或崩溃

如果您发现Home Assistant意外重启或崩溃，可能是某个集成影响了系统稳定性。Home Assistant具有一个内置的调试选项，可以帮助找到实现错误。它还可以阻止许多不安全的线程操作导致系统崩溃。启用调试对系统有轻微的性能影响，且不建议长期使用。要启用调试，请在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中添加以下内容：

homeassistant:
  debug: true

启用调试后，定期检查Home Assistant系统日志以获取新消息。

相关主题