← 返回博客
Tutorial发布于 2026-04-28· 14 分钟阅读

给 Next.js 添加 Stripe 订阅 2026 完整指南:从结账到 Webhook

WangNan, author at Uncorne
作者 WangNan
出品方 Uncorne · 更新于 2026-11-12

这是在 Next.js 中接入 Stripe 订阅、且不会在生产翻车的最短路径。四个部件,没有灌水——还补上多数指南略过的验证细节。

订阅集成很少在顺利路径上失败。客户点订阅、创建 Checkout Session、Webhook 触发、数据库里的标志翻转——每一篇教程里这套都成立。出问题的是它周围的一切:伪造的 Webhook 被 200 确认、重试的事件被应用两次、取消后套餐永远翻不回来,或者密钥被不小心打进了浏览器包。这篇指南覆盖整个闭环,包括那些失败情况。

Next.js 中 Stripe 订阅的四个部件
Next.js 中 Stripe 订阅的四个部件

前置条件

写代码前需要三样东西:

  • 一个使用 App Router 的 Next.js 15 项目。从头开始的话,以 App Router 文档为准。
  • 一个处于测试模式的 Stripe 账户,拿到密钥和 Webhook 签名密钥。
  • 一张带 plan 列的 users 表,或独立的 subscriptions 表,且你的服务端能写入它。

一次性设好环境变量,测试与生产凭据放在不同环境:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
NEXT_PUBLIC_APP_URL=http://localhost:3000

绝不要给 Stripe 密钥加 NEXT_PUBLIC_ 前缀。带这个前缀的变量会被嵌入浏览器包,按定义就是公开的。客户端里的密钥不是捷径,而是一张已经公开的凭据。

第 1 步:创建产品与价格

在 Stripe 后台创建一个带周期性价格的 Product,例如 Pro 每月 12 美元。把 Price ID 写进 STRIPE_PRICE_ID_PRO,绝不硬编码进源码。Price ID 在测试与生产模式下不同,硬编码测试价格是一个沉默的生产 bug:结账看起来正常,但金额或币种是错的。

维护一份从你自己的套餐名到价格 ID 的映射,这样区域定价或分层定价就是改数据而不是改代码。把套餐建模为数据,而不是代码里的分支。一个包含 id、priceId 与 entitlements 的 PLANS 对象,让功能权限去检查 canExport 或 seats 这样的能力,而不是套餐名——这样重命名一个档位不需要改每一条路由。它也让按年计费变简单:给同一个套餐加第二个价格 ID,让结账路由从经过校验的请求里挑选。

Stripe 后台中带周期性价格的 Product 及其 Price ID
Stripe 后台中带周期性价格的 Product 及其 Price ID

第 2 步:安装并配置 SDK

用 npm install stripe 安装官方服务端 SDK。在模块作用域实例化一个客户端,让初始化只发生一次:

import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-02-24.acacia",
});

在代码里固定 API 版本,而不是让它浮动。Stripe 发布新版本时,你要做的是读更新日志、主动选择升级,而不是在账单里发现行为变了。

第 3 步:结账路由

POST /api/checkout 读取请求的套餐、解析价格 ID,创建一个 mode: "subscription" 的 Checkout Session,带上用户的 client_reference_id,以及明确的 success_url 与 cancel_url。把托管页 URL 返回浏览器。除非有具体理由,否则不要自己造支付表单。

创建会话前要求用户已登录。游客结账会找不到授权对象:Webhook 按用户 id 或付款邮箱发放权限,如果两者都对不上账户,license 就没有主人。在路由处理器里从 cookies 读取会话,而不是读客户端传来的用户 id。

export async function POST(req: Request) {
  const user = await getSessionUser();           // 服务端,来自 cookies
  if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });

  const { plan } = await req.json();
  const priceId = PLANS[plan]?.priceId;          // 来自环境变量,绝不来自客户端
  if (!priceId) return Response.json({ error: "bad plan" }, { status: 400 });

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    client_reference_id: user.id,
    customer_email: user.email,
    success_url: `${APP_URL}/billing?status=success`,
    cancel_url: `${APP_URL}/billing?status=cancel`,
  });

  return Response.json({ url: session.url });
}

有两个细节很关键。价格来自你的环境变量,绝不来自请求体——否则客户端可以花一美元选你的企业版价格。另外两个 URL 都要明确写出;依赖默认值会把用户送到 Stripe 拥有的页面。完整的会话参数见 Checkout Sessions API 参考。

从已登录用户到 Stripe 托管支付页的结账会话流程
从已登录用户到 Stripe 托管支付页的结账会话流程

第 4 步:Webhook 是真相来源

浏览器不可信。客户端声称「支付成功」什么都证明不了。由 Stripe 签名的 Webhook 才是权威信号。在解析 JSON 之前,先用 Stripe-Signature 头校验原始 body:

export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  if (!sig) return new Response("missing signature", { status: 400 });

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      await req.text(),                  // 精确的原始字节
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response("invalid signature", { status: 400 });
  }

  if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 });
  await markProcessed(event.id);

  switch (event.type) {
    case "checkout.session.completed":
      await grantPlan(event.data.object.client_reference_id, "pro");
      break;
    case "customer.subscription.deleted":
      await revokePlan(event.data.object.metadata.userId);
      break;
  }
  return new Response(null, { status: 200 });
}

先解析再重新序列化会改变字节,导致 HMAC 校验失败。验签失败——缺头、HMAC 不对、JSON 损坏——必须抛错并返回 HTTP 400。用 200 确认伪造请求是安全漏洞,不是无害的空操作。签名方案见 Webhook 签名校验,完整事件目录见 Webhook 事件类型。

被忽略的事件与被拒绝的事件不同。一条合法验签、但你并不处理的事件,应当记录下来并以 200 加 ignored 标记回应。绝不要把 200-ignored 用在验签失败上。

解析 JSON 之前用签名头校验原始 Webhook body
解析 JSON 之前用签名头校验原始 Webhook body

第 5 步:让 Webhook 幂等

Stripe 会重试 Webhook。没有防重放,一次支付会变成两次升级,一次取消会变成幽灵退款。把已处理的事件 id 记进一张表,对 event_id 加唯一约束,并在生效之前先插入:

create table processed_events (
  event_id text primary key,
  received_at timestamptz not null default now()
);

插入本身就是锁:并发的重试用同一个 id 时,主键冲突会告诉你跳过。把「检查并标记」做成一个原子步骤,而不是「先读后写」——后者会留下竞态窗口。创建会话时把 userId 挂到订阅 metadata 上,这样取消事件不用按邮箱查就能找到对应账户。

在提交使用任何模板之前,还有一点值得检查:它到底处不处理取消 Webhook?很多模板只处理 checkout.session.completed,忘了 customer.subscription.deleted,结果客户取消后还永远保有权限。在代码里搜这两个事件类型,如果只有一个,收第一笔钱之前把另一个补上。

每条事件 id 只应用一次的幂等日志
每条事件 id 只应用一次的幂等日志

第 6 步:功能权限

每个受保护路由或 Server Action 都从数据库读套餐——绝不读客户端状态,也绝不读结账后你自己写的 cookie。套餐未激活就返回 402。你的 AI 接口、源码 ZIP 下载、席位限制都挂在这一个检查上:

export async function requirePro() {
  const user = await getSessionUser();
  if (!user) throw new HttpError(401);
  const { data } = await supabase
    .from("profiles")
    .select("plan")
    .eq("id", user.id)
    .single();
  if (data?.plan !== "pro") throw new HttpError(402, "Upgrade required");
}

隐藏按钮的客户端检查是 UX,不是安全。真正算数的是服务端检查。如果你是在 Server Action 而不是路由处理器里做这件事,规则一样;Server Actions 文档说明了如何把变更留在服务端。

套餐未激活时返回 402 的服务端功能权限检查
套餐未激活时返回 402 的服务端功能权限检查

第 7 步:让客户自行管理与取消

客户门户能把每一次取消都从工单里拿掉。在服务端创建 Billing Portal 会话,把用户重定向过去。门户处理换卡、改套餐与取消,Stripe 发出对应的 Webhook,所以你的数据库无需额外代码就能保持同步。周期中途升级的按天折算也由它替你算好——别自己拿时间戳去算。

第 8 步:跑通整个闭环

用测试模式和卡号 4242 4242 4242 4242,过期时间填任意未来日期,CVC 随意:

  1. 完成结账,确认套餐在数据库里翻转。
  2. 在门户取消,确认它翻回来。
  3. 重放一条已捕获的 checkout.session.completed 事件,确认只应用一次。
  4. 发一条签名被篡改的 Webhook,确认返回 400 而不是 200。
  5. 用免费用户调用 Pro 接口,确认返回 402。

本地接收可以用 Stripe CLI 转发事件(stripe listen --forward-to localhost:3000/api/webhooks),并把打印出的签名密钥复制到 STRIPE_WEBHOOK_SECRET。如果你的 CI 已经部署 Preview,用一个带独立 Webhook 端点与独立密钥的 Preview URL 来测会更干净。

如果一份 env 就能跑通整个闭环,你的计费就是真的。如果某一步还需要手动改数据库才能「收尾」,那就还没完成。

用测试卡、重放、错误签名与 402 检查跑通测试闭环
用测试卡、重放、错误签名与 402 检查跑通测试闭环

常见故障

| 现象 | 可能原因 | 修复 | | --- | --- | --- | | 每条 Webhook 都返回 400 | 签名密钥不对,或解析发生在验签之前 | 用原始 body 和对应端点的密钥 | | 套餐永远不翻转 | 事件处理了,但 client_reference_id 为空 | 创建会话前要求登录 | | 套餐翻转两次 | 事件 id 没有幂等 | event_id 唯一表,生效前原子插入 | | 本地结账正常、生产不行 | 生产环境用了测试 key 或测试 Price ID | 测试与生产环境分离,启动时校验 key | | 免费用户能过权限检查 | 用了客户端状态作真相来源 | 每次请求都从数据库读套餐 |

模板能帮上什么

好的模板会把第 3–6 步预先接好,并把它们放在与支付商无关的接口后面。当你为了新地区接入 Creem、PayPal、Waffo 或 Lemon Squeezy 时,这一点就值钱了:你写的是新适配器,而不是把结账与 Webhook 逻辑在整个应用里重写一遍。Uncorne 用同一套结账与 Webhook 契约提供五家支付商适配器,上面这条 Stripe 路径就是参考实现。

验证规则不随支付商改变。对原始字节验签、对事件 id 去重、只从服务端写库、把功能权限留在服务端。先用 Stripe 把这些学会,它们可以直接迁移。更深的架构理由写在如何用 Next.js 搭建 SaaS里。

诚实的总结

Next.js 里的 Stripe 订阅就是四个部件:后台里的产品与价格、要求已登录用户的结账路由、先验签再解析且先去重再写库的 Webhook,以及服务端套餐权限。这四件事做对,顺利路径会变得几乎无聊——这正是计费系统该有的样子。其余一切,从区域定价到第二家网关,都只是这个闭环之上的适配器。

FAQ

验签之前可以先解析 Webhook body 吗?+

不行。先用 Stripe-Signature 头校验精确的原始字节,再解析。先解析再重新序列化会改变字节、破坏 HMAC 校验,此时应返回 400。

为什么游客结账会发不出授权?+

Webhook 按用户 id 或付款邮箱发放权限。若没人登录、付款邮箱又对不上账户,license 就没有主人。创建 Checkout Session 前要求登录。

被忽略的 Webhook 响应是什么意思?+

返回 200 并标记 ignored,表示事件合法已验签但不属于我们处理的类型。它绝不能用于验签失败——那些必须是 400。把被忽略的事件记录下来,以便和失败区分。

如何防止重试的 Webhook 把用户升级两次?+

把已处理事件 id 存入带 event_id 唯一约束的表,并在生效前原子插入。重试到达时主键冲突会告诉你跳过。先读后写会留下竞态窗口。

该用 Stripe Checkout 还是嵌入式支付元素?+

先用托管 Checkout:它是接入订阅最短的路径,支付界面由 Stripe 托管。只有当你需要在自己的页面里控制支付体验时,才换成嵌入式元素。两者的 Webhook 逻辑完全相同。

全部常见问题 · Markdown 版本(供 AI 智能体阅读)