Home Assistant 中 homeassistant.reload_all 动作完全指南一条命令热重载全部 YAML 配置【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇技术指南围绕 Home Assistant 的homeassistant.reload_all动作展开它能在不重启系统的情况下一次性重载所有支持热重载的 YAML 配置并附带配置校验保护机制。读完本文你将掌握在 UI 与 YAML 两种方式下调用该动作的完整方法理解它的执行顺序、失败回退逻辑、权限要求与生效时机并学会将其与homeassistant.reload_core_config、homeassistant.reload_custom_templates、homeassistant.check_config、homeassistant.restart等动作组合使用。动作概览一次调用重载全部可热加载配置homeassistant.reload_all是 Home Assistant 核心Core提供的动作其官方定位是Reloads all YAML configuration that can be reloaded without a restart重载所有无需重启即可重载的 YAML 配置文档定义位于 source/_actions/homeassistant.reload_all.markdown。它的核心价值在于批量生效它会对每一个支持 reload 动作的 domain 调用其 reload 动作例如automation、script、group、input_boolean、input_number、input_select、input_text、input_datetime、scene、template、zone、counter、input_button等。除各域自身的配置外它还会额外重载Core 配置core configuration、主题themes以及自定义 Jinja2 模板custom Jinja templates。典型使用场景你在多个 YAML 文件中分别修改了自动化、脚本、分组等配置如果逐个调用各域的 reload 动作会非常繁琐使用reload_all可以一步完成全部变更的生效而不必重启 Home Assistant。安全机制执行前的配置校验Check Configurationreload_all并不是盲目重载它在执行前会先运行一次基础配置检查basic configuration check。这一设计非常关键如果配置检查通过则继续执行各域的重载如果配置检查失败则什么都不重载并且该动作会抛出错误raises an error。也就是说该动作遵循先校验、后应用的原子化语义要么全部成功重载要么全部保持原状避免出现部分配置已更新、部分仍是旧值的中间状态。文档原话明确指出If that check fails, nothing is reloaded and the action raises an error.source/_actions/homeassistant.reload_all.markdown 正文。当重载失败时修复报错后重试即可。这一前置校验逻辑与homeassistant.restart、homeassistant.check_config两个动作共享同类的安全设计——它们的详细行为分别记录在 source/_actions/homeassistant.restart.markdown 与 source/_actions/homeassistant.check_config.markdown 中可互相印证。权限要求仅管理员可执行reload_all涉及系统级配置变更因此只有具有管理员权限administrator rights的用户才能运行此动作。这与homeassistant.restart、homeassistant.reload_core_config、homeassistant.reload_custom_templates、homeassistant.check_config等核心管理类动作的权限要求一致。如果你的登录用户不是管理员调用该动作会因权限不足而失败。在 UI 中配置该动作自动化 / 脚本如果你偏向可视化配置Home Assistant 会在编辑器中逐步引导你完成配置无需编写 YAML。操作步骤source/_actions/homeassistant.reload_all.markdown进入设置 自动化与场景Settings Automations scenes。打开一个现有的自动化或脚本或者选择创建自动化创建新自动化。如果是新建自动化需要在When触发条件部分添加一个触发器脚本不需要触发器它们由其他对象调用时才会运行。在Then do执行动作部分选择添加动作Add action。搜索并选择Reload all Home Assistant configuration重载所有 Home Assistant 配置。点击保存。在 YAML 中调用该动作在 YAML 配置中该动作的标识符为homeassistant.reload_all。基本调用示例如下source/_actions/homeassistant.reload_all.markdownaction: homeassistant.reload_all在自动化中配合触发器使用一个完整的最小示例alias: Apply all YAML changes on demand trigger: - platform: event event_type: my_custom_event action: - action: homeassistant.reload_allOptions in YAMLYAML 参数该动作没有任何可选参数no options。调用时只需指定action字段无需、也不支持传入data。执行范围与Good to know要点该动作的执行范围可以从文档的 Good to know 章节source/_actions/homeassistant.reload_all.markdown中得到精确确认该动作包含了 Reload Core configuration 与 Reload custom Jinja2 templates 两个动作所完成的工作并且额外重载主题themes。如果配置检查失败则什么都不重载。此时应修复报错信息中提示的错误然后重新尝试。需要留意的是包含并不完全等于等价单独调用reload_core_config或reload_custom_templates时它们各自作用于homeassistant:配置段或custom_templates目录且不会触发全局配置检查而reload_all是它们加上主题重载的超级集并带有一层全局校验。生效时机局部动作的细节由于reload_all内部会调用reload_core_config与reload_custom_templates这两个局部动作的生效时机约束同样适用于reload_all的对应部分Core 配置homeassistant:配置段及其引用的文件重载后立即应用但其中新增的customize:设置要等到受影响实体的状态下一次更新时才会生效见 source/_actions/homeassistant.reload_core_config.markdown。自定义 Jinja2 模板custom_templates目录中的模板重载后新的模板值在下一次渲染导入这些模板的表达式时才会生效而非即时生效见 source/_actions/homeassistant.reload_custom_templates.markdown。什么样的配置能通过 reload 生效需要特别说明边界reload_all只能重载支持热重载的 YAML 配置。这意味着它只覆盖实现并注册了 reload 动作的集成/域。对于不提供 reload 机制的配置例如新增的集成条目、configuration.yaml中某些仅在启动时解析的顶层组件、依赖运行内存对象的变更仍然需要完整重启 Home Assistant 才能生效。与相邻管理动作的协同使用reload_all在官方文档中被明确标注了三个关联动作source/_actions/homeassistant.reload_all.markdown 的 related_actions 字段它们共同构成配置生效的完整工具箱动作作用是否重启关键特性homeassistant.reload_all重载全部可热重载 YAML 配置否前置配置检查失败则全部不重载并报错homeassistant.reload_core_config仅重载homeassistant:段及其引用文件否customize:变更在下一次实体状态更新时生效homeassistant.reload_custom_templates仅重载custom_templates目录中的 Jinja2 模板否新值在下一次模板渲染时生效homeassistant.check_config只校验 YAML 配置不加载、不应用否出错时生成持久化通知并写入日志homeassistant.restart校验通过后重启 Home Assistant是校验失败则取消重启支持 safe_mode典型工作流推荐日常 YAML 修改后的快速生效修改了多个域的 YAML 后直接调用homeassistant.reload_all一步完成重载如果报错说明配置有问题修复后重试。改动涉及启动时加载的配置先用 check_config 动作或重启前的自动检查确认配置无误再调用homeassistant.restartsource/_actions/homeassistant.restart.markdown。restart同样带有配置检查保护检查失败时不会重启而是创建 ID 为persistent_notification.homeassistant_check_config的持久化通知并在日志中记录失败原因。需要安全模式排障当自定义集成或自定义仪表板卡片导致 Home Assistant 无法正常启动时可调用homeassistant.restart并传入data: { safe_mode: true }safe_mode为布尔类型默认false可选参数进入安全模式此时系统不会加载自定义集成与自定义卡片。相关动作的 YAML 参考示例重载 Core 配置action: homeassistant.reload_core_config重载自定义 Jinja2 模板action: homeassistant.reload_custom_templates仅校验配置不应用任何变更action: homeassistant.check_config带安全模式重启action: homeassistant.restart data: safe_mode: true排查与排障建议当reload_all抛出错误或行为不符合预期时按以下顺序排查检查返回错误信息reload_all失败时不会静默跳过错误信息中会指出配置检查失败的原因按提示修复对应的 YAML 文件。查看日志配置检查的详细失败原因会写入 Home Assistant 日志。若配置检查发现问题Home Assistant 还会创建持久化通知相关行为可参见 source/_actions/homeassistant.check_config.markdown。确认权限确认调用者账号为管理员。确认重载边界如果改动属于不支持热重载的配置如集成新增、核心启动参数请改用homeassistant.restart完成生效。区分生效时机customize:变更等待实体状态更新、模板变更等待下次渲染——如果改动看起来没生效很可能是时机问题而非调用失败。总结homeassistant.reload_all是 Home Assistant 中批量热重载 YAML 配置的高效入口一次调用即可对所有支持 reload 的域、Core 配置、主题和自定义 Jinja2 模板进行重载前置配置检查保证了要么全部成功、要么全部不变的可靠性无参数的设计让它极易在 UI 与 YAML 两种模式下使用。理解它与reload_core_config、reload_custom_templates、check_config、restart的分工与边界能帮你建立一套安全、高效的配置生效工作流在绝大多数场景下免去频繁重启的等待时间。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考