# 什么是推送通知 API？什么时候需要它？

> 推送通知 API 把一次 HTTP 请求变成手机上的一条提醒。本文介绍它的作用、同名的两类产品、请求的样子，以及选择前该检查什么。

*04.10.2026*

<!-- source: https://pocketalert.app/zh/blog/what-is-a-push-notification-api -->

推送通知 API 是一种 Web 服务：当你的代码发出请求时，它会把一条消息显示在手机锁屏上。你发送一个包含标题和正文的 HTTP 请求，服务把它交给 Apple 或 Google，手机在几秒内显示出来，无论有没有应用处于打开状态。

核心思路就是这样。区别在于：通知面向谁，以及你想自己掌控多少投递环节。

## 同名的两类产品

搜索“push notification API”，你会看到两类几乎没有交集的产品。

**面向你的用户推送的平台。** 例如 Firebase Cloud Messaging、Apple Push Notification service、OneSignal 等。你需要开发一个移动应用，发布到 App Store 和 Google Play，从每次安装中收集设备令牌，然后向成千上万的人发送产品或营销通知。这个 API 只是一个漫长项目的最后一步。

**向你自己推送的服务。** 例如 Pocket Alert、Pushover、ntfy 等。应用已经存在：你在自己的手机上安装它，获取 API 密钥，然后从脚本、服务器和其他服务中发送提醒。无需发布应用，也无需收集令牌。部署完成、备份失败、收到付款，都可以即时通知你。

本指南讨论的是第二类。如果你在开发消费级应用，需要触达它的用户，那你需要的是第一类，下面的大部分内容都不适用于你。

## 发送一条通知时会发生什么

四个环节，大部分都是看不见的：

1. 你的代码向服务发送一个 HTTPS 请求，包含标题、消息和你的 API 密钥。
2. 服务验证密钥、保存消息，并决定它该发往哪里：发给你的哪些设备，以什么优先级发送。
3. 服务把通知交给平台自己的推送网络：iPhone 使用 APNs，Android 使用 Firebase Cloud Messaging。
4. Apple 或 Google 通过每部手机本来就保持的连接把通知送达，手机随即显示。

后两个环节解释了为什么应用关闭时推送依然有效，而且不会耗尽电池：手机从不主动轮询任何服务。完整路径请参阅[推送通知的工作原理：APNs 与 FCM](/blog/how-push-notifications-work-apns-fcm)。

## 为什么不直接对接 Apple 和 Google？

你当然可以，前提是你在两大应用商店都有自己的应用。要在中间不借助任何服务、直接推送到自己的手机，你需要：

- 一个 Apple Developer Program 会员资格，以及带有推送权限的 iOS 应用；另一半则需要一个 Firebase 项目和一个 Android 应用。
- 一个 APNs 签名密钥和一个 Firebase 服务账号，以及为每种请求签名的代码。
- 一套从应用中收集设备令牌、并在令牌变化时保持更新的机制。
- 两种请求格式、两套优先级模型和两组错误码。

如果应用本身就是你的产品，这是一个合理的项目。但如果只是为了“cron 任务失败时通知我”，这套机制就太重了。推送通知服务已经替所有人做过一次这些工作。

## 请求长什么样

使用 Pocket Alert 发送通知，只需一个带认证的 POST 请求：

```bash
curl -X POST https://api.pocketalert.app/v1/messages \
  -H 'Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Deploy finished", "message": "api v2.4.1 is live"}'
```

响应为 `201 Created`，附带已保存的消息以及它发出时所用的优先级。任何带 HTTP 客户端的语言都可以发送同样的请求，更多终端示例请参阅[使用 curl 发送推送通知](/use-cases/curl-push-notifications)。

只有 `title` 和 `message` 是必填项。对提醒最有用的可选字段包括：

- `level` 设置通知的提醒强度：`silent`、`low`、`default`、`high` 或 `critical`。
- `actions` 为通知添加最多三个操作按钮：打开一个 URL、触发一个 HTTP 请求，或复制一个值。
- `send_at` 或 `delay` 可以延迟发送，而不是立即发送（付费套餐）。
- `application_id` 和 `device_id` 用于指定它属于哪个项目，以及发给哪部手机。

## 不只是 API 的三种接入方式

当你不必为每个来源编写代码时，推送通知 API 才最有用。

- **HTTP API**，适用于你自己的脚本、任务和应用。
- **Webhook URL**，适用于已经能发送 Webhook 的服务。GitHub、Stripe、Grafana 或 Sentry 可以直接把它们自己的 JSON 发送到 Pocket Alert 的 Webhook，而 `%repository.name%` 这类占位符会把字段提取到通知中，中间无需任何代码。[创建你的第一个 Webhook URL](/blog/create-your-first-webhook-url) 有详细步骤。
- **CLI 和 MCP 服务器**，适用于终端和 AI 智能体：在 shell 中执行 `pocketalert send "Build done" "All tests passed"`（[CLI](/tools/cli)），或者让 Claude 或 Cursor 在长任务结束时调用 `create_message` 工具（[MCP](/tools/mcp)）。

## 哪些场景会用到它

大多数提醒可以归为以下几类：

- **出问题了。** 服务器停止响应、cron 任务以非零状态退出、备份没有运行。参见 [cron 任务告警](/use-cases/cron-job-alerts)和[服务器监控](/use-cases/server-monitoring)。
- **任务完成了。** 部署、长时间构建、12 小时的 3D 打印、AI 智能体的任务。参见[部署告警](/use-cases/deployment-alerts)。
- **发生了你关心的事。** 一笔付款、一次注册、一份表单提交。参见[付款告警](/use-cases/payment-alerts)和[注册告警](/use-cases/signup-alerts)。
- **即将发生某事。** 一张 14 天后过期的证书。参见 [SSL 证书过期告警](/use-cases/ssl-expiration-alerts)。

它们的共同点是：有一件事需要有人立刻知道，而不是等到下一次打开控制台或收件箱时才发现。

## 选择前需要检查什么

这个领域的每项服务都是通过 HTTP 请求发送推送的，真正的差别在于周边的一切：

- **平台。** 有些只支持 iPhone（Bark、The Notification App），Gotify 唯一的官方应用只支持 Android。如果需要接收提醒的人使用另一种手机，这一点就决定了选择。
- **优先级。** 备份失败的提醒能否与新用户注册的提示音不同？紧急提醒能否穿透勿扰模式？
- **入站 Webhook。** 服务能否直接发送它自己的 JSON，还是每个来源都需要脚本来重新整理数据？
- **历史与日志。** 当提醒没有送达时，是否有调用记录以及它的处理结果？
- **限额与定价。** 按天、按月还是终身计算，达到上限后会怎样？
- **运营方式。** 是托管服务，还是你自己维护的服务器。

我们在[替代方案](/alternatives)页面中，就这些要点将 Pocket Alert 与 Pushover、ntfy、Pushbullet、Bark、Gotify 等服务进行了比较，并说明了每个服务在哪些方面更合适。

## 常见问题

### 推送通知 API 和 Firebase Cloud Messaging 是一回事吗？

FCM 是一种推送通知 API：由 Google 提供，供你开发并发布的应用使用。Pocket Alert 这类服务构建在 FCM 和 APNs 之上，替你处理应用、密钥和设备令牌，你只需要发送 HTTP 请求。

### 我需要开发移动应用吗？

如果只是向你自己或团队发送提醒，则不需要。你只需安装现成的应用，例如适用于 [iPhone 或 Android](/get-app) 的 Pocket Alert，然后向它发送即可。只有当你需要向自己的用户推送时，才需要开发自己的应用。

### 是免费的吗？

许多服务都提供免费套餐。Pocket Alert 的免费套餐每天可发送 50 条消息，无需绑定信用卡，足以满足大多数个人提醒需求；付费套餐每月 6 美元起，每天可发送 1,000 条。详情请见[定价页面](/pricing)。

### 投递有多快？

通常从发出请求到显示在锁屏上只需几秒钟。不过 Apple 和 Google 并不保证时效：如果手机没有信号，或处于严格的省电模式，通知会在重新连接后才送达。

### 推送、短信还是邮件？

需要立即关注的事情用推送，摘要和记录用邮件，而对方完全没有智能手机应用时则用短信。相关权衡请参阅[推送通知与短信对比](/blog/push-notifications-vs-sms)以及[推送通知与邮件告警对比](/blog/push-vs-email-alerts)。

[免费注册账号](/signup)，复制你的 API 密钥，然后上面那条 curl 命令就是你的第一条推送。
