Home Assistant 中使用 ntfy.publish 动作发送富文本推送通知的完整指南
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
本文以 Home Assistant 文档仓库中的 ntfy.publish 动作文档 为核心，系统讲解如何通过ntfy.publish动作向 ntfy topic 发布通知，涵盖 UI 可视化配置与 YAML 两种方式、优先级 / 标签 / 附件 / 延迟投递 / 动作按钮等全部可选参数，并结合ntfy.clear（标记已读）与ntfy.delete（删除）两个关联动作，给出从门铃抓拍到"死循环开关"（dead man's switch）的完整自动化示例。读完本文，你将掌握在 Home Assistant 自动化与脚本中发送带标题、Markdown、图片附件、交互按钮的高质量 ntfy 通知，并能通过 sequence ID 对已发通知做更新、清除与删除。
ntfy.publish 动作是什么
ntfy是一个基于 HTTP 的简单 pub-sub（发布/订阅）推送通知服务，可以把通知发送到手机或桌面端。Home Assistant 的 ntfy 集成（参见 ntfy 集成文档，于 2025.5 版本引入）允许你向 ntfy.sh 官方服务或自建 ntfy 实例发布推送通知，并且具备 event（事件）、notify（通知）、sensor（用量统计传感器）、update（自托管实例版本更新）等平台能力，质量等级为 platinum。
Publish notification（ntfy.publish）动作即把一条通知消息发布到某个 ntfy topic 的动作。它发布于 Home Assistant 2025.10 版本。与基础版notify.send_message不同，它充分发挥了 ntfy 服务的全部能力：你可以自定义消息的优先级、链接、附件、标签、表情符号，以及点击通知后的跳转行为。从 2025.10 版本发布说明 可以看到，该版本为 ntfy 集成带来了重大升级——支持携带标签、图标、URL 和附件发送更丰富、更可定制的通知，并新增了事件平台用于订阅 topic 并在收到消息时触发自动化。
在 Home Assistant 的自动化和脚本中，通知类动作的目标（target）通常是集成配置好的 notify 实体（形如notify.mytopic）。每个配置的 topic 都会生成一个设备及对应的 notify 实体。
在 UI 中添加"发布通知"动作
在自动化或脚本中发送通知，操作步骤如下：
- 进入设置 > 自动化与场景（Automations & scenes）。
- 打开一个已有的自动化或脚本，或选择创建自动化 > 创建新自动化。
- 如果是新自动化，在触发条件（When）部分添加触发器；脚本不需要触发器，它们在被其他对象调用时才运行。
- 在执行（Then do）部分选择添加动作（Add action）。
- 在搜索框中搜索并选择ntfy: Publish notification。
- 在目标（Targets）下选择要通知的 topic（详见下文"动作的目标"）。
- 可选：自定义消息优先级、加入表情符号，或添加 URL、附件、动作按钮等交互元素。
- 选择保存（Save）。
动作的目标（Targets）
该动作必须有目标。目标即动作的作用对象，可以是单个实体、设备、区域、楼层或标签，Home Assistant 会对其背后所有匹配的 notify 实体执行动作（详见 targets.md 模板）：
- 实体（Entity）：某个具体的 notify 实体，例如
notify.living_room。 - 设备（Device）：隶属于某设备的所有 notify 实体。
- 区域（Area）：某个房间或区域内的所有 notify 实体。
- 楼层（Floor）：某楼层上的所有 notify 实体。
- 标签（Label）：共享某个标签的所有 notify 实体。
同一动作还可以混合选择不同类型的目标，例如同时添加一个具体实体和一个区域，让动作同时对两者生效。
UI 中的可选参数
UI 中各选项说明如下（所有参数均为可选）：
| 选项 | 说明 |
|---|---|
| 标题（Title） | 通知消息的标题。 |
| 消息（Message） | 通知正文。未提供时默认为字符串triggered。 |
| 使用 Markdown 格式（Format as Markdown） | 为消息正文启用 Markdown 格式化（语法参见 Markdown 指南）。 |
| 标签/表情符号（Tags/Emojis） | 为通知添加标签或表情符号。使用smile这类短代码的表情会显示在通知标题或正文中，其余标签显示在通知内容下方。 |
| 消息优先级（Message priority） | 所有消息都有优先级，它决定手机通知的紧迫程度（取决于配置的振动模式、通知铃声以及通知栏/弹窗中的可见性）。 |
| 点击 URL（Click URL） | 点击通知时打开的 URL。 |
| 延迟投递（Delay delivery） | 设置消息投递延迟，最短 10 秒，最长 3 天。 |
| 附件 URL（Attachment URL） | 通过 URL 附加图片或其他文件。 |
| 附加本地文件（Attach local file） | 从本地文件、相机或图片媒体源上传附件。选择相机实体时，会捕获当前画面快照并附加到通知中。 |
| 附件文件名（Attachment filename） | 指定附件的自定义文件名（含扩展名，例如snapshot.jpg）。未提供时默认文件名是attachment（例如attachment.jpg）。 |
| 转发到邮箱（Forward to email） | 指定将通知转发到的邮箱地址，例如mail@example.com。 |
| 电话呼叫（Phone call） | 要拨打的电话号码，用于通过文本转语音（TTS）朗读消息。需要 ntfy Pro 及事先完成电话号码验证。 |
| 图标 URL（Icon URL） | 在通知文本旁显示的图标，仅支持 JPEG 和 PNG 图片。 |
| 动作按钮（Action buttons） | 最多三个动作按钮，显示在通知下方，点击/轻触即执行。可选打开网站/应用、发送 Android 广播、发送 HTTP 请求或复制到剪贴板。 |
| 序列 ID（Sequence ID） | 输入消息或序列 ID 来更新已有通知，或指定一个序列 ID 供之后更新、清除（标记已读并关闭）或删除通知时引用。 |
注意：所有参数都是可选的。如果message留空，通知将使用默认文本
triggered；如果未指定priority，则使用默认优先级 3。
提示：完整的表情短代码支持列表可查阅 ntfy 的 emoji 参考文档。
在 YAML 中使用 ntfy.publish
在 YAML 中，该动作写作ntfy.publish。最基本的示例如下：
action: ntfy.publish target: entity_id: notify.mytopic这会向 topicmytopic发送一条内容为triggered的通知。
YAML 中的可选参数
YAML 有时还提供 UI 中不可用的额外选项，适合更复杂的用例。完整参数如下：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | string | 否 | — | 通知消息的标题。 |
message | string | 否 | triggered | 通知正文。 |
markdown | boolean | 否 | false | 设为true以对消息正文启用 Markdown 格式化。 |
tags | list | 否 | — | 为通知添加标签或表情符号，字符串列表，元素为标签或 emoji 短代码。 |
priority | integer | 否 | 3 | 通知优先级（1 = 最低，2 = 低，3 = 默认，4 = 高，5 = 最高）。 |
click | string | 否 | — | 点击通知时打开的 URL。 |
delay | map | 否 | — | 设置消息投递延迟，最短 10 秒，最长 3 天。 |
attach | string | 否 | — | 通过 URL 附加图片或其他文件。 |
attach_file | map | 否 | — | 通过上传本地文件或相机媒体源附加图片或其他文件。 |
filename | string | 否 | — | 附件的自定义文件名（含扩展名）。 |
email | string | 否 | — | 将通知转发到的邮箱地址。 |
call | string | 否 | — | 要拨打的电话号码，通过 TTS 朗读消息。 |
icon | string | 否 | — | 通知文本旁显示的图标 URL。 |
action | list | 否 | — | 最多三个动作按钮，类型见下文。 |
sequence_id | string | 否 | — | 消息或序列 ID，用于更新已有通知，或供之后更新、清除、删除通知时引用。 |
其中priority参数直接对应 ntfy 的优先级体系：1最低、2低、3默认、4高、5最高，通知的紧迫程度会影响手机的振动模式、铃声和通知栏可见性。
动作按钮的 YAML 配置
action为列表类型，最多三个按钮。每个按钮由type区分类型，可选view、http、broadcast、copy四种。
动作view：打开网站或应用
点击按钮时打开指定的网站或应用：
- type: view label: "查看车库摄像头" url: "http://homeassistant.local/lovelace/garage" clear: true| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 是 | — | 填view。 |
label | string | 是 | — | 通知中动作按钮的标签。 |
url | string | 是 | — | 点击动作时打开的 URL。 |
clear | boolean | 否 | false | 点击动作按钮后清除通知。 |
动作http：发送 HTTP 请求
点击按钮时向指定 URL 发送 HTTP 请求，可用于触发 webhook 或其他自动化：
- type: http label: "开启派对模式" url: "http://homeassistant.local/api/webhook/party-mode-webhook" method: "POST"| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 是 | — | 填http。 |
label | string | 是 | — | 通知中动作按钮的标签。 |
url | string | 是 | — | HTTP 请求发送到的 URL。 |
method | string | 否 | POST | 请求使用的 HTTP 方法。 |
headers | map | 否 | — | 随 HTTP 请求发送的附加请求头（键值对）。 |
body | string | 否 | — | HTTP 请求体（payload）。 |
clear | boolean | 否 | false | 点击动作按钮后清除通知。 |
动作broadcast：发送 Android 广播
点击按钮时发送一个 Android 广播 intent，常用于唤起手机端 App 的特定行为，例如在 Sleep as Android 中开始睡眠追踪：
- type: broadcast label: "开始睡眠追踪" intent: "com.urbandroid.sleep.START_SLEEP_TRACK"| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 是 | — | 填broadcast。 |
label | string | 是 | — | 通知中动作按钮的标签。 |
intent | string | 否 | io.heckel.ntfy.USER_ACTION | 触发broadcast动作时发送的 Android intent 名称。 |
extras | map | 否 | — | 以键值对形式包含在 intent 中的 extras。 |
clear | boolean | 否 | false | 点击动作按钮后清除通知。 |
动作copy：复制到剪贴板
点击按钮时把指定值复制到剪贴板，适合分享临时信息（如访客 Wi-Fi 密码、门禁码）：
- type: copy label: "复制密码" value: "GuestPass1234!"| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 是 | — | 填copy。 |
label | string | 是 | — | 通知中动作按钮的标签。 |
value | string | 是 | — | 要复制到剪贴板的值。 |
clear | boolean | 否 | false | 点击动作按钮后清除通知。 |
实战示例
以下示例均来自 ntfy.publish 动作文档，可直接复制到自动化或脚本中使用。
发送带摄像头快照的通知
有人按门铃时发送一张摄像头抓拍快照：
action: ntfy.publish target: entity_id: notify.mytopic data: title: Someone is at the door attach_file: media_content_id: media-source://camera/camera.demo_camera media_content_type: application/vnd.apple.mpegurl filename: camera-snapshot.jpg tags: - bellhop_bell这里attach_file以 Home Assistant 的媒体源形式引用摄像头实体，filename指定了附件文件名（含扩展名），tags中的bellhop_bell会作为 emoji 短代码渲染在通知中。
发送"死循环开关"（Dead Man's Switch）通知
该通知在指定延迟之后才被投递，充当所谓的死循环开关。要重置计时器（例如每日打卡成功后），只需再次发送该通知——这会取消先前已排程的通知，并重新开始一个 24 小时倒计时：
action: ntfy.publish target: entity_id: notify.mytopic data: title: "Dead Man's Switch Activated" message: "I haven't checked in for 24 hours. Please check on me." priority: 5 delay: hours: 24 sequence_id: "dead-mans-switch-check-in" tags: - warning - skull要点解析：
delay使用 map 形式（此处为hours: 24）设置延迟投递，符合最短 10 秒、最长 3 天的约束。sequence_id是关键：它是"死循环开关"机制的核心。再次发布携带相同sequence_id的通知会覆盖并取消前一条待投递通知，从而重置倒计时。priority: 5表示最高优先级，确保 24 小时未打卡时通知以最紧急的方式提醒。tags中的warning与skull会作为标签/表情显示在通知中。
发送带"打开 URL"按钮的通知
通知附带一个动作按钮，点击后打开指定 URL，例如直接跳转到相关仪表盘或摄像头画面：
action: ntfy.publish target: entity_id: notify.mytopic data: message: "The garage door has been open for 10 minutes." actions: - type: view label: "View Garage Camera" url: "http://homeassistant.local/lovelace/garage" clear: true发送可触发 webhook 的通知
创建一个"Party Mode"按钮，点击后通过 HTTP 请求让 Home Assistant 运行一个脚本：
action: ntfy.publish target: entity_id: notify.mytopic data: message: "The party is starting!" actions: - type: http label: "Start Party Mode" url: "http://homeassistant.local/api/webhook/party-mode-webhook" method: "POST"发送带"复制到剪贴板"按钮的通知
分享临时信息（如访客 Wi-Fi 密码或门禁码）：
action: ntfy.publish target: entity_id: notify.mytopic data: title: "Guest Wi-Fi Password" message: "Here is the guest Wi-Fi password for today." actions: - type: copy label: "Copy Password" value: "GuestPass1234!"发送可触发 Android 广播的通知
通过 Android 广播 intent 在 Sleep as Android 中启动睡眠追踪：
action: ntfy.publish target: entity_id: notify.mytopic data: message: "Time for bed?" actions: - type: broadcast label: "Start sleep tracking" intent: "com.urbandroid.sleep.START_SLEEP_TRACK"配合 ntfy.clear 与 ntfy.delete 管理已发通知
从 2026.2 版本发布说明 可以看到，该版本为 ntfy 集成添加了sequence ID支持，允许更新通知，并新增了两个动作：dismiss（清除/标记已读）和 delete（删除）。这两个动作均以sequence_id或消息 ID 作为必填参数，用来定位目标通知。
ntfy.clear：清除（标记已读）通知
Dismiss notification（ntfy.clear）动作把 topic 中先前发送的消息标记为已读但不删除，适合通知不再需要关注、但后续仍想查看或引用时使用（详见 ntfy.clear 动作文档）。YAML 基本用法：
action: ntfy.clear target: entity_id: notify.mytopic data: sequence_id: "motion-detected"一个典型的自动化场景是：后院移动被清除时，自动把先前发送的"检测到移动"通知标记为已读：
automation: triggers: - trigger: motion.cleared target: area_id: backyard actions: - action: ntfy.clear data: sequence_id: "motion-detected" target: entity_id: notify.mytopicntfy.delete：删除通知
Delete notification（ntfy.delete）动作从 ntfy topic 中删除一条通知（详见 ntfy.delete 动作文档）。YAML 基本用法：
action: ntfy.delete target: entity_id: notify.mytopic data: sequence_id: "motion-detected"与 clear 的差别在于：clear 只是标记已读、通知仍保留，而 delete 会彻底移除该通知。同样也可以在"移动已清除"的自动化中把通知彻底删除：
automation: triggers: - trigger: motion.cleared target: area_id: backyard actions: - action: ntfy.delete data: sequence_id: "motion-detected" target: entity_id: notify.mytopic使用提醒：要清除或删除通知，必须提供其消息 ID 或 sequence ID，而 sequence ID 正是在发送（
ntfy.publish）时通过sequence_id参数指定的。因此，设计"发布 → 更新/清除/删除"的完整通知生命周期时，请务必在发布阶段为通知设置稳定的sequence_id。
集成背景与使用限制
前置条件与 topic 配置
使用这些动作前，需要先在设置 > 设备与服务中完成 ntfy 集成的配置：
- 服务 URL：官方服务使用
https://ntfy.sh，也可填写其他公共 ntfy 服务或自建实例的地址（如https://your-ntfy-instance.com）。 - 认证（可选）：如果服务器启用了访问控制，部分 topic 需要正确凭据才能订阅或发布。集成使用access token认证访问受保护的 topic，提供用户名和密码后 Home Assistant 会自动生成并使用 access token。
- 添加 topic：选择添加主题（Add topic），然后选择"输入主题名"（从 ntfy App 或网站复制现有 topic 名称）或"生成主题名"（让集成自动生成随机 topic 名）。
配置连接时的参数：Service URL（默认https://ntfy.sh）、Verify SSL certificate（是否校验 SSL 证书）、Username（可选）与Password（可选）。每个 topic 还有可选的过滤选项（按优先级、标签、标题、消息内容过滤），这些过滤只作用于集成订阅消息时产生的 event 实体。
注意：topic 可能没有密码保护，请选择不易被猜到的名称；如果发送敏感信息，建议保留 topic 并限制其访问权限。
速率限制
ntfy 服务设有各种速率与用量限制。官方 ntfy.sh 服务允许每 burst 最多 60 条消息，补充速率为每 5 秒 1 条（即 60 条的完整容量约 5 分钟补满）。其余用量限制取决于账户等级，可在Account → Usage查看。自建实例可配置更高或完全取消这些限制。在设计高频通知自动化（例如批量告警脚本）时，应将这些限制纳入考虑。
排障建议
集成依赖与 ntfy 服务之间的活跃网络连接。如果遇到问题，请先确认网络稳定且 ntfy 服务可达，并留意服务端可能的维护或意外宕机。上报问题时，建议启用调试日志（若该路径存在）、重启集成、问题复现后停止调试日志，并尽可能附带诊断数据。
总结
ntfy.publish是 Home Assistant 中向 ntfy 推送富通知的入口动作，与ntfy.clear、ntfy.delete共同构成了完整的通知生命周期管理能力。通过priority、tags、markdown、attach_file、delay、action（view / http / broadcast / copy）和sequence_id等参数的组合，你可以把一条普通推送升级为带图片快照、可交互操作、可延迟投递、可事后撤回的企业级告警方案。更多资料可继续阅读：
- ntfy.publish 动作文档
- ntfy.clear 动作文档
- ntfy.delete 动作文档
- ntfy 集成完整文档
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
