给 Next.js 添加 Stripe 订阅 2026 完整指南:从结账到 Webhook
这是在 Next.js 中接入 Stripe 订阅、且不会在生产翻车的最短路径。四个部件,没有灌水——还补上多数指南略过的验证细节。
订阅集成很少在顺利路径上失败。客户点订阅、创建 Checkout Session、Webhook 触发、数据库里的标志翻转——每一篇教程里这套都成立。出问题的是它周围的一切:伪造的 Webhook 被 200 确认、重试的事件被应用两次、取消后套餐永远翻不回来,或者密钥被不小心打进了浏览器包。这篇指南覆盖整个闭环,包括那些失败情况。

前置条件
写代码前需要三样东西:
- 一个使用 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,让结账路由从经过校验的请求里挑选。

第 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 参考。

第 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 用在验签失败上。

第 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,结果客户取消后还永远保有权限。在代码里搜这两个事件类型,如果只有一个,收第一笔钱之前把另一个补上。

第 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 文档说明了如何把变更留在服务端。

第 7 步:让客户自行管理与取消
客户门户能把每一次取消都从工单里拿掉。在服务端创建 Billing Portal 会话,把用户重定向过去。门户处理换卡、改套餐与取消,Stripe 发出对应的 Webhook,所以你的数据库无需额外代码就能保持同步。周期中途升级的按天折算也由它替你算好——别自己拿时间戳去算。
第 8 步:跑通整个闭环
用测试模式和卡号 4242 4242 4242 4242,过期时间填任意未来日期,CVC 随意:
- 完成结账,确认套餐在数据库里翻转。
- 在门户取消,确认它翻回来。
- 重放一条已捕获的
checkout.session.completed事件,确认只应用一次。 - 发一条签名被篡改的 Webhook,确认返回 400 而不是 200。
- 用免费用户调用 Pro 接口,确认返回 402。
本地接收可以用 Stripe CLI 转发事件(stripe listen --forward-to localhost:3000/api/webhooks),并把打印出的签名密钥复制到 STRIPE_WEBHOOK_SECRET。如果你的 CI 已经部署 Preview,用一个带独立 Webhook 端点与独立密钥的 Preview URL 来测会更干净。
如果一份 env 就能跑通整个闭环,你的计费就是真的。如果某一步还需要手动改数据库才能「收尾」,那就还没完成。

常见故障
| 现象 | 可能原因 | 修复 | | --- | --- | --- | | 每条 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 逻辑完全相同。