# Klipper 推送通知：打印提醒直达手机

> 打印完成、失败或暂停时，手机即时收到推送。Moonraker 内置通知器加上 Pocket Alert Webhook，无需插件，只需一段配置。

*09.10.2026*

<!-- source: https://pocketalert.app/zh/blog/klipper-print-notifications -->

一段十二小时的打印不需要你守在旁边。你需要的是在它完成的那一刻知道，更重要的是在它停下来的那一刻知道。

Klipper 本身就能告诉你这两件事。Moonraker 是 Mainsail 和 Fluidd 背后的 API 服务器，它内置了一个通知器，会在打印事件发生时触发，并通过 [Apprise](https://github.com/caronc/apprise) 发送。把它指向一个 Pocket Alert Webhook，每次打印完成、失败、取消或暂停，都会以手机推送通知的形式到达你的手机。无需插件，不用在树莓派上额外部署服务，只需一段配置。

## 你需要准备

- 一台运行 Klipper 和 Moonraker 的打印机。如果你能在浏览器里打开 Mainsail 或 Fluidd，就说明已经有 Moonraker。
- 一个免费的 [Pocket Alert](/) 账户，以及 [iPhone 或 Android](/get-app) 手机上的应用。
- 大约五分钟。

## 第一步：在 Pocket Alert 中创建 Webhook

在控制台中打开 [Webhooks](/webhooks)，新建一个 Webhook：

- **名称**：填打印机名，例如 `Voron 2.4`。这个名称会成为推送标题（`Webhook Voron 2.4`），如果你有多台打印机，一眼就能看出是哪台需要你处理。
- **应用**和**设备**：通知发送的目标。
- **消息**：粘贴以下模板：

```
%title%
%message%
```

保存后复制 Webhook 地址，格式类似 `https://p4a.me/wh/<your-webhook-id>`。

为什么使用这个模板：Moonraker 会把每条通知交给 Apprise，而 Apprise 的 JSON 通知器会发送如下结构的数据：

```json
{
  "version": "1.0",
  "title": "❌ Print error",
  "message": "3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]",
  "attachments": [],
  "type": "info",
  "level": "high"
}
```

模板中的每个 `%key%` 都会被替换为 JSON 中对应字段的值。推送的第一行显示标题，下面是消息内容。关于模板路径的更多说明，请参阅[创建你的第一个 Webhook 地址](/blog/create-your-first-webhook-url)。

## 第二步：在 moonraker.conf 中添加通知器

打开 `moonraker.conf`（Mainsail 中在 **Machine** 下，Fluidd 中在 **Configuration** 下），在文件末尾添加以下三个段落。把 `YOUR_WEBHOOK_ID` 替换为 Webhook 地址中的 ID。

```ini
[notifier pocketalert_done]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID
events: complete
title: ✅ Print complete
body: {event_args[1].filename}

[notifier pocketalert_fail]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: error, cancelled
title: ❌ Print {event_name}
body: {event_args[1].filename} {event_args[1].message}

[notifier pocketalert_pause]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: paused
title: ⏸ Print paused
body: {event_args[1].filename}: check the printer
```

各部分的作用：

- **`jsons://`** 是 Apprise 基于 HTTPS 的 JSON 通知器，它会把上面的数据发送到你的 Webhook。
- **`events`** 指定触发该段的打印状态。Moonraker 支持 `started`、`complete`、`error`、`cancelled`、`paused` 和 `resumed`。
- **`?:level=high`** 告诉 Apprise 在 JSON 中加入 `"level": "high"`。Pocket Alert 会读取这个字段，并以高优先级发送推送。在 iPhone 上，这会作为时效性通知送达，并能穿透专注模式。"complete" 段没有设置 level，因此会作为普通推送送达。
- **`{event_args[1]}`** 是事件发生后的任务状态，与 Klipper 的 `print_stats` 对象一致：`filename` 是 G-code 文件名，`message` 是打印失败时 Klipper 给出的错误文本。
- **`{event_name}`** 是触发的事件名，因此一个段落可以同时覆盖 `error` 和 `cancelled`，标题仍能说明具体发生了哪种情况。

## 第三步：重启 Moonraker 并测试

在 Mainsail 或 Fluidd 的电源菜单中重启 Moonraker，或通过 SSH 执行：

```bash
sudo systemctl restart moonraker
```

在用耗材做测试之前，先用 curl 检查 Webhook。下面的命令发送的数据结构与 Apprise 相同：

```bash
curl -X POST https://p4a.me/wh/YOUR_WEBHOOK_ID \
  -H 'Content-Type: application/json' \
  -d '{"title":"❌ Print error","message":"test.gcode Move out of range","level":"high"}'
```

如果手机震动，说明 Pocket Alert 这一端工作正常。接下来打印一个小模型，并在第一层完成后取消，几秒钟内你应该会收到 `❌ Print cancelled`。

## 手机上会收到什么

夜间打印失败时，锁屏上会显示类似这样的内容：

```
Webhook Voron 2.4
❌ Print error
3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]
```

不用解锁手机，你就知道是哪台打印机、哪个文件，以及停机的原因。

## 按你的需求调整

以下改动都只是在同一个文件里做小幅修改。

- **安静记录打印开始。** 添加一个段落，设置 `events: started` 和 `?:level=silent`。开始事件会记入消息历史，但不发出声音。
- **让失败通知把你叫醒。** 把失败段落中的 `?:level=high` 改为 `?:level=critical`。在 Android 上，关键提醒会穿透勿扰模式。关键提醒属于付费功能，免费套餐下消息仍会以高优先级送达。详情请参阅[关键提醒](/use-cases/critical-alerts)。
- **多台打印机。** 每台打印机配置一个 Webhook，并以机器命名。推送标题会告诉你哪台停了。
- **来自你自己宏的提醒。** Moonraker 还支持 `gcode` 事件，因此 Klipper 宏可以发送任意文本。适用于更换耗材或耗材用尽传感器等场景。

在 `moonraker.conf` 中：

```ini
[notifier pocketalert_macro]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: gcode
title: 🧵 Printer needs you
body: {event_message}
```

在 `printer.cfg` 中：

```ini
[gcode_macro NOTIFY_FILAMENT_CHANGE]
gcode:
  {action_call_remote_method("notify",
                             name="pocketalert_macro",
                             message="Filament change needed")}
```

在你的 `NOTIFY_FILAMENT_CHANGE` 宏中，或在耗材传感器的 `M600` 中调用 `runout_gcode`。

## 如果没有收到通知

- **在控制台中查看 Webhook。** [Webhook 历史](/features/webhook-history)会记录每次调用及其原始数据。如果没有记录，说明 Moonraker 从未连到 Pocket Alert。如果有记录且带有错误，记录中会说明原因。
- **查看 `moonraker.log`。** Moonraker 会把通知器的错误记录在这里，同时也会记录已安装的 Apprise 版本。大多数安装中，它位于 `~/printer_data/logs/moonraker.log`。
- **推送内容为空。** 模板中的键必须与 Apprise 的数据结构一致：应使用 `%title%` 和 `%message%`，而不是 `%body%`。

## 为什么不用插件？

Klipper 的 Telegram 机器人和远程访问服务功能更多：摄像头截图、延时摄影、远程控制。但它们也会在树莓派上增加另一个需要安装和持续更新的服务。如果你只想要"打印完成时告诉我，失败时叫醒我"，Moonraker 本身已经完成了发送，Pocket Alert 只需负责接收。

如果打印机放在[自托管实验室](/use-cases/homelab-alerts)旁边，它的提醒会和你的服务器、备份及 cron 任务提醒一起出现在同一个应用中，拥有统一的历史记录和相同的优先级设置。

## 常见问题

### 需要在树莓派上安装什么吗？

不需要。通知器是 Moonraker 的一部分，Apprise 会作为依赖随之安装。你只需编辑 `moonraker.conf` 并重启 Moonraker。

### Mainsail 和 Fluidd 都支持吗？

支持。两者都是 Moonraker 的网页界面，而通知器运行在 Moonraker 中，因此配置完全相同。你可以在任一界面中编辑 `moonraker.conf`。

### 能同时接收多台打印机的通知吗？

可以。为每台打印机创建一个 Webhook，并以机器名称命名。Webhook 名称会成为推送标题。

### 打印失败会在夜里把我叫醒吗？

使用 `level=high` 时，推送会在 iPhone 上以时效性通知送达，并能穿透专注模式。要在 Android 上穿透勿扰模式，请在付费套餐中使用 `level=critical`。

### 是免费的吗？

是的。Webhook 在免费套餐中可用，每个事件消耗你每日上限中的一条消息，一次普通打印通常只发送一到两条。

[创建 Webhook](/webhooks)，粘贴配置，你的下一次打印就会在完成时告诉你。
