用 QStash JS SDK 在无服务器/边缘环境实现…

当你需要在 Next.js、Vercel、Cloudflare Workers、Deno、Node.js 等无服务器或边缘运行时中发布 HTTP 消息、调度 cron、延迟投递、构建 FIFO 队列、验证 webhook 签名或处理失败重试时使用。

适用场景

解决思路

1. 安装 SDK：运行 `npm install @upstash/qstash`。
2. 初始化客户端：从 `@upstash/qstash` 导入 `Client`，用 `new Client({ token: process.env.QSTASH_TOKEN! })` 创建实例，token 从环境变量读取。
3. 发布消息：调用 `client.publishJSON({ url, body })` 向 HTTP 端点发送 JSON 消息，例如 `url: "https://my-api.example.com/webhook"`、`body: { event: "user.created", userId: "123" }`。
4. 发布到 URL 组：参考 `fundamentals/url-groups.md`，将消息扇出到多个端点。
5. 创建定时/延迟投递：参考 `fundamentals/schedules.md`，使用 cron 表达式调度或延迟消息。
6. 管理 FIFO 队列与流控：参考 `fundamentals/queues-and-flow-control.md`，用队列实现有序处理并控制并行度。
7. 本地开发：参考 `fundamentals/local-development.md`，通过 `devMode: true` 自动启动本地 QStash dev server。
8. 验证入站消息签名：使用 `Receiver` 类进行核心签名验证，参考 `verification/receiver.md`。
9. 按平台验证签名：Next.js 项目参考 `verification/platform-specific/nextjs.md`，覆盖 App Router、Pages Router 和 Edge Runtime。
10. 配置回调：参考 `advanced/callbacks.md` 设置消息处理完成后的回调。
11. 处理死信队列（DLQ）：参考 `advanced/dlq.md`，对失败消息进行恢复处理。
12. 消息去重：参考 `advanced/deduplication.md`，避免重复投递。
13. 区域迁移与多区域支持：参考 `advanced/multi-region/summary.md`；如需验证多区域环境变量配置，可运行 `advanced/multi-region/verify-multi-region-setup.ts`（无需参数）。
14. 构建复杂持久化工作流：若需串联多条 QStash 消息、自动状态管理、重试与容错，改用独立的 QStash Workflow SDK（`@upstash/workflow`）。
15. 始终使用 `Receiver` 类验证入站 QStash 消息。
16. token 和签名密钥一律通过环境变量管理。
17. 根据场景设置合适的重试次数和超时时间。
18. 需要有序处理且可控并行度时使用队列。
19. 为失败消息实现 DLQ 处理以支持恢复。

适用边界 · 注意事项

• 需要构建跨多步、带自动状态管理和容错的持久化工作流时，应使用 `@upstash/workflow` 而非核心 QStash SDK。
• 依赖非 HTTP 协议或非无服务器/边缘运行时的消息系统场景不适用。