upstash-qstash-js

QStash JavaScript SDK

QStash 是一种基于 HTTP 的消息传递和调度解决方案，适用于无服务器和边缘运行时。本技能可帮助你高效使用 QStash JS SDK。

捆绑的文档和源代码

在编写或调试 SDK 代码之前，请先查看 node_modules/@upstash/qstash/docs/ 中捆绑的文档，以及 node_modules/@upstash/qstash/src/ 中可读的 TypeScript 源代码。如果相关文件存在，请阅读并搜索；否则，请使用本技能中的参考资料。

何时使用本技能

适用于以下场景：

• 向端点或 URL 组发布 HTTP 消息
• 创建定时或延迟消息传递
• 管理可配置并行度的 FIFO 队列
• 验证来自 QStash 的传入 Webhook 签名
• 实现回调、DLQ 处理或消息去重

快速开始

安装 SDK

npm install @upstash/qstash

基本发布

import { Client } from "@upstash/qstash";

const client = new Client({
  token: process.env.QSTASH_TOKEN!,
});

const result = await client.publishJSON({
  url: "https://my-api.example.com/webhook",
  body: { event: "user.created", userId: "123" },
});

核心概念

有关 QStash 的基本操作，请参阅：

• 发布消息
• 定时任务
• 队列和流量控制
• URL 组
• 本地开发 — 通过 devMode: true 自动启动开发服务器

验证传入消息：

• Receiver 验证 - 使用 Receiver 类进行核心签名验证
• 平台专用验证器：
  • Next.js - App Router、Pages Router 和 Edge Runtime

高级功能：

• 回调
• 死信队列（DLQ）
• 消息去重
• 区域迁移和多区域支持
  • 如有需要，可使用多区域环境变量设置验证脚本。运行时无需传入参数

平台支持

QStash JS SDK 可在多种平台上运行：

• Next.js（App Router 和 Pages Router）
• Cloudflare Workers
• Deno
• Node.js（v18+）
• Vercel Edge Runtime
• SvelteKit、Nuxt、SolidJS 及其他框架

关于 Workflow SDK 的说明： 如果要构建由多条 QStash 消息串联而成的复杂持久化工作流，可以考虑使用独立的 QStash Workflow SDK（@upstash/workflow）。Workflow SDK 可帮助你编排多步骤流程，并提供自动状态管理、重试和容错能力。本技能文件介绍的是核心 QStash 消息 SDK。

最佳实践

• 始终使用 Receiver 类验证传入的 QStash 消息
• 使用环境变量保存令牌和签名密钥
• 根据使用场景设置适当的重试次数和超时时间
• 使用队列实现有序处理并控制并行度
• 为失败消息实现 DLQ 处理，以便进行恢复