← 返回博客
Comparison发布于 2026-03-03· 6 分钟阅读

自带 Stripe 与登录的 Next.js SaaS 模板:2026 检查指南

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

搜索「自带 Stripe 与登录的 Next.js SaaS 模板」听起来像是在挑功能。其实不是。你真正在问的是:那 60% 的通用部分——注册、数据库、计费、控制台、部署——我还要亲手写多少?本文给出一套十分钟的实操检查法,适用于你正在考虑的任何模板,包括本站交付的这一套。

自带 Stripe 与登录的 Next.js SaaS 模板检查清单
自带 Stripe 与登录的 Next.js SaaS 模板检查清单

先看四项不可妥协

把它们当成通过/不通过,而不是加分项。模板缺任何一项,你一个月内就得返工——而且往往在最糟的时点:真实客户已经在等着了。

| 领域 | 必须已经接好的东西 | 代码里该看到什么 | | --- | --- | --- | | 登录 | 邮箱魔法链接加 OAuth,默认开启行级安全 | Supabase Auth 集成,以及你真能读懂的 RLS 策略,不是空壳 | | 计费 | 托管结账,加上一个会翻转数据库套餐标志的 Webhook | 事件先验签、再去重、最后写库——顺序不能乱 | | 数据库 | Postgres,含预置表结构与迁移历史 | 初始 schema 已入库,而不是 README 里一段散装 SQL | | 部署 | Vercel 就绪配置,一条命令通往生产 | 环境变量按名字写清文档,并附示例文件 |

只有一个登录表单加一个 Stripe Checkout 跳转 的模板,是演示。由已验签的 Webhook 签名 作为权限唯一真相来源的模板,才是生意。

Webhook 验签是多数模板翻车的地方

这一段值得读两遍。浏览器跳转会骗人:用户关掉标签页、支付商重试、测试触发两次。只有已验签的 Webhook 才应该改变客户的权限。

我们用的契约刻意写得非常精确:

  • 签名缺失、无效或格式损坏 → 立即抛错,路由返回 400。
  • 合法已验签但无需处理的事件 → 返回空列表,路由返回 200 并标记 ignored。
  • 已见过的事件 id → 在写套餐或 license 之前直接跳过。

写反了就是安全漏洞,不是风格偏好。本代码库早期版本把验签失败当成「没有事件」并返回 200,等于让伪造请求看起来成功了。永远别用安静的 200 换掉一个该有的 400。

Webhook 验签流程图,错误签名返回 400
Webhook 验签流程图,错误签名返回 400

在 POST /api/webhook 路由里,每个支付适配器验签失败都会抛错。空数组只表示一件事:事件合法且已验签,只是无需动作——例如本应用并不售卖的产品的 checkout.session.completed。重放事件在写库前会按事件 id 在 webhook_events 表里去重。如果你还不熟悉事件类型,Stripe 的 Webhook 事件参考 配上自家服务商文档,是最清晰的读物。

幂等:你在第一次退款时才遇到的 bug

支付商一定会重试,因为网络不可靠。非幂等的 Webhook 处理器会把同一套餐写两次、重复计量用量,甚至重新打开客户已取消的订阅。修复方法并不巧妙:记录事件 id,先查一遍,再让写操作以「该 id 不存在」为条件。

这事很少在上线当天出问题。它出现在第一次退款、第一次重复事件、第一次客户质疑账单的时候。到那时再补幂等,意味着你要改动所有已经交付的权限路径。在需要之前就把它做进去。

还有一个相关陷阱:把客户端当成证据。浏览器可以显示成功页,而 Webhook 根本没到。权限必须从数据库读取,而数据库只由已验签事件写入——绝不从查询字符串或本地状态标志读取。

一家通道还是五家服务商?

Uncorne 默认使用 Waffo Pancake,这是一种 Merchant of Record,替你处理销售税与 VAT——用大白话讲就是 merchant of record 模式。Stripe、Creem、PayPal、Waffo Acquiring 与 Lemon Squeezy 可在生成时切换;如果你自带计费,none 也是有效选择。

它们全部收在同一份 PaymentProvider 接口和一个 POST /api/webhook 路由之下。业务代码永远不需要按网关分支。这种隔离正是重点:网关是配置项,不是架构决策。取舍见五家支付网关对比。

单一 Webhook 契约下的五家支付适配器
单一 Webhook 契约下的五家支付适配器

十分钟评估法,真能跑起来

别再读功能清单了,把模板跑起来。

git clone <模板仓库地址>
cd starter && cp .env.example .env.local
# 填好登录与计费变量,然后
npm install && npm run dev

然后按顺序试:

  1. 用邮箱和 OAuth 各注册一次。两者都应进入受保护页面。
  2. 去撞付费功能的付费墙。应该被服务端拦住,而不只是在界面里藏起来。
  3. 完成一次测试结账。数据库里的套餐标志应无需刷新页面就翻转。
  4. 用错误签名打一次 Webhook。必须返回 400,绝不能是 200。
  5. 同一个合法事件重放两次。第二次写入必须是空操作。

任何一步被「现在得自己写代码」卡住,你就得到答案了。好模板会让这五步都变得无聊。

下载包里还应该有什么

能让你交付的模板,给出的不应只是一个跑起来的应用。检查你实际收到的 ZIP 里装了什么。未选中的模块应该被真正删掉,而不是注释掉:残留的支付商、认证后端与功能开关会变成死代码,日后你得逐一审计。导航也应被改写,避免任何链接指向已被裁剪掉的页面。

包里还应带给你和你的工具一份机器可读的说明。找一份写明仓库契约与完成定义的 AGENTS.md、一份锁定你所选视觉风格的设计指南,以及配套的编辑器规则。这些很重要,因为它们能阻止 AI 编程助手把你已经刻意移除的模块又加回来。为什么读取顺序很关键,见我们的 Agent-Ready 文档指南。

最后检查品牌面。一个卖源码的生成器,必须把自己的营销页、定价组件与生成器内部代码从客户下载包里剪掉。残留一句别人产品的指代不是美观问题——它会一路发到你的用户手里。CI 应下载并类型检查 18 组代表性构建组合,这样某条裁剪规则破坏某个配置时,会在客户看到之前就失败。

诚实的限制

没有哪个模板是完整的。这一套有真实的资料修改、角色管理接口与账单门户,但本地 SQLite 回退只是账户目录,不是完整认证服务:没有 MFA、OAuth 与会话轮换。SMTP 明确未实现——你要接入 REST 邮件服务或安全空操作。在能让写入路径更简单的地方,使用了 Server Actions。

这种诚实本身就是特性。声称什么都能做的模板,往往把缺口藏到你已经投入之后才暴露。选一个你能接受其缺口的——并且 Webhook 该返回 400 时就返回 400 的。

关于作者:WangNan 在 https://www.uncorne.com 分享交付源码型 SaaS 的实践。

FAQ

自带 Stripe 与登录的 Next.js SaaS 模板,最先该检查什么?+

先查 Webhook 验签。合格模板必须对缺失或无效签名返回 HTTP 400,在写权限前按事件 id 去重,并且只把「合法已验签但无需处理」当作空事件列表。相比之下其它都是表面功夫。

模板必须用 Stripe 吗?+

不必。Stripe 是文档最全的处理商,但若你无公司主体却面向全球销售,Waffo Pancake 或 Lemon Squeezy 这类 Merchant of Record 能免去销售税处理。关键是结账与 Webhook 有一份与支付商无关的契约。

行级安全在这里到底保护什么?+

RLS 让数据库强制执行租户边界,即使应用代码忘了写 WHERE 子句。在基于 Supabase 的模板里,用户所属表应从第一次迁移起就有 auth.uid() 策略,而不是事后补上。

没有支付账户也能评估模板吗?+

能。克隆、填示例环境变量、启动服务,用错误签名打一次 Webhook——必须返回 400。还可以把同一事件重放两次,确认第二次写入是空操作。真实结账仍需要沙箱账户。

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