saas-starter 订阅暂停/恢复实战从用户点击到 Webhook 同步的完整指南【免费下载链接】saas-starterGet started quickly with Next.js, Postgres, Stripe, and shadcn/ui.项目地址: https://gitcode.com/GitHub_Trending/sa/saas-starter上个月有客户说团队预算被砍想先停三个月、下季度再续——这个场景正是 saas-starter 订阅暂停/恢复功能要解决的让用户不取消订阅就能停掉计费需要时再一键续上。项目基于 Next.js、PostgresDrizzle ORM、Stripe 和 shadcn/ui本文直接拆给你看要改哪 4 个地方、怎么自测。一张图看懂订阅状态到底怎么流转动代码之前先把状态机定下来。暂停不是你在数据库里加的一个额外字段而是 Stripe 官方认可的订阅状态你的系统只做同步。状态含义常见触发active正常计费试用结束扣款成功或暂停后恢复paused停止扣费工作区和数据保留用户在 Billing Portal 选择暂停canceled订阅终止用户取消或扣款永久失败动手3 步暂停你的订阅站在用户视角暂停就是三次点击点仪表盘上的管理订阅进 Stripe Billing Portal → 选暂停模式 → 确认返回。选模式immediate立即停止计费本期不再扣款at_period_end本期服务用到头下期起暂停。确认Portal 落库变更Stripe 同时把customer.subscription.paused事件推给后端 webhook。回仪表盘状态徽标从绿色活跃变琥珀色已暂停用户一眼明白——号没丢只是停了扣费。之所以能这么顺是因为 Portal 是 Stripe 提供的现成界面项目只在配置里打开对应能力不用自己画暂停按钮。入口处的createCustomerPortalSession负责换一张带正确配置的 Portal 链接这就是整个功能看起来大、实际很小的原因。恢复订阅恢复是暂停的反向操作进同一个 Portal点恢复确认卡片仍有效卡过期的先换卡完事。Stripe 推customer.subscription.resumed回来库里状态变回active徽标重新变绿。全程不需要重新注册或重建工作区。幕后改动到底发生在哪 4 个地方把仓库翻一遍真正要动的只有 4 处全部可肉眼验证且都不碰主结账链路。1. teams 表的subscriptionStatus列lib/db/schema.ts 里 teams 表本来就留了三个 Stripe 同步列不用加字段、不用跑迁移列作用stripeCustomerId从 Stripe Customer 反查本地团队stripeSubscriptionId关联具体的 Stripe 订阅subscriptionStatus同步 active/paused/canceled 等状态2. Portal 配置里加 pauselib/payments/stripe.ts 的 Portal 配置features里已有subscription_update、subscription_cancel补一项即可subscription_pause: { enabled: true, mode: immediate // 或 at_period_end }3. webhook 新增两个事件分支app/api/stripe/webhook/route.ts 的 switch 现在只接updated/deleted加上暂停/恢复case customer.subscription.paused: case customer.subscription.resumed: { const sub event.data.object as Stripe.Subscription; const team await getTeamByStripeCustomerId(sub.customer as string); await updateTeamSubscription(team.id, { subscriptionStatus: sub.status paused ? paused : active }); break; }4. 前端状态徽标仪表盘页面读team.subscriptionStatus做分支paused渲染琥珀色 Badge已暂停将于 x 日恢复active渲染绿色。想再严格些就在 app/(dashboard)/layout.tsx/layout.tsx) 里对暂停态灰掉部分功能入口。自测5 步验证暂停/恢复真的生效✅ 测试卡4242 4242 4242 4242五步走完闭环本地跑起来用测试卡过一次结账确认teams表里subscriptionStatus是active。调暂停接口或在 Portal 里点暂停# 暂停 curl -X POST https://api.stripe.com/v1/subscriptions/sub_xxx/pause \ -u sk_test_xxx: -d pause[behavior]immediate # 恢复 curl -X POST https://api.stripe.com/v1/subscriptions/sub_xxx/resume -u sk_test_xxx:查库subscriptionStatus应变为paused。发恢复命令状态回到active。看仪表盘徽标从琥珀变绿。若没变先查 webhook 签名校验有没有过。避坑清单下面四条都是上线后会被真实扎到的地方。webhook 重试Stripe 投递失败会自动重发处理逻辑必须幂等——同一状态写两次等价于写一次。邮件通知暂停/恢复要通知到用户Stripe Billing 自带邮件或自己发否则用户根本不知道扣费状态变了。权限控制只有团队管理员能进账单管理入口入口处做角色校验。暂停期功能限制状态为paused时灰掉邀请成员、数据导出等功能避免停了计费却还在消耗资源的尴尬。【免费下载链接】saas-starterGet started quickly with Next.js, Postgres, Stripe, and shadcn/ui.项目地址: https://gitcode.com/GitHub_Trending/sa/saas-starter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考