Next.js 订阅支付启动器

用于高性能SaaS应用的一体化启动套件。

特性

• 使用 Supabase 进行安全的用户管理和身份验证
• 基于PostgreSQL的强大数据访问和管理工具 Supabase
• 集成 Stripe Checkout 和 Stripe客户门户
• 通过 Stripe webhooks 自动同步定价计划和订阅状态

演示

• https://subscription-payments.vercel.app/

架构

逐步设置

部署此模板时，步骤顺序很重要。请按以下顺序操作以正常运行。

开始部署

Vercel部署按钮

Vercel部署将在您的GitHub账户上创建一个包含此模板的新仓库，并指导您创建新的Supabase项目。Supabase Vercel部署集成将设置必要的Supabase环境变量，并运行SQL迁移以在您的账户上设置数据库架构。您可以在项目的表格编辑器中检查创建的表。

如果自动设置失败，请创建Supabase账户，并在需要时创建新项目。在您的项目中，导航至SQL编辑器并从快速启动部分选择"Stripe订阅"启动模板。

配置身份验证

按照此指南设置GitHub的OAuth应用，并配置Supabase使用它作为身份验证提供者。

在您的Supabase项目中，导航至auth > URL配置并设置您的主要生产URL（例如https://your-deployment-url.vercel.app）作为网站URL。

接下来，在您的Vercel部署设置中，添加一个名为NEXT_PUBLIC_SITE_URL的新生产环境变量，并将其设置为相同的URL。请确保取消选择预览和开发环境，以确保预览分支和本地开发正常工作。

[可选] - 为部署预览设置重定向通配符（如果您通过部署按钮安装，则不需要）

如果您通过上面的"部署到Vercel"按钮部署了此模板，可以跳过此步骤。Supabase Vercel集成将为您设置重定向通配符。您可以通过访问Supabase的身份验证设置来检查，您应该在"重定向URL"下看到一个重定向列表。

否则，为了使身份验证重定向（电子邮件确认、魔法链接、OAuth提供者）在部署预览中正常工作，请导航至身份验证设置并将以下通配符URL添加到"重定向URL"：https://*-username.vercel.app/**。您可以在文档中阅读更多关于重定向通配符模式的信息。

如果您通过上面的"部署到Vercel"按钮部署了此模板，可以跳过此步骤。Supabase Vercel集成将为您运行数据库迁移。您可以通过访问Supabase项目的表格编辑器来检查，并确认有带有种子数据的表。

否则，导航至SQL编辑器，粘贴Supabase schema.sql 文件的内容，然后点击运行以初始化数据库。

[可能可选] - 设置Supabase环境变量（如果您通过部署按钮安装，则不需要）

如果您通过上面的"部署到Vercel"按钮部署了此模板，可以跳过此步骤。Supabase Vercel集成将为您设置环境变量。您可以通过访问Vercel项目设置并点击"环境变量"来检查，将会看到一个环境变量列表，旁边显示Supabase图标。

否则，导航至API设置并将它们粘贴到Vercel部署界面中。复制项目API密钥并粘贴到NEXT_PUBLIC_SUPABASE_ANON_KEY和SUPABASE_SERVICE_ROLE_KEY字段中，复制项目URL并粘贴到Vercel的NEXT_PUBLIC_SUPABASE_URL中。

恭喜，这完成了Supabase的设置，即将完成！

配置Stripe

接下来，我们需要配置Stripe来处理测试支付。如果您还没有Stripe账户，现在创建一个。

对于以下步骤，请确保打开"测试模式"开关。

创建Webhook

我们需要在Stripe的开发者部分创建一个webhook。如上面的架构图所示，这个webhook是连接Stripe和您的Vercel无服务器函数的部分。

1. 在测试端点页面上点击"添加端点"按钮。
2. 输入您的生产部署URL，后跟/api/webhooks作为端点URL。（例如https://your-deployment-url.vercel.app/api/webhooks）
3. 在"选择要监听的事件"标题下点击选择事件。
4. 在"选择要发送的事件"部分点击选择所有事件。
5. 复制签名密钥，因为我们在下一步需要它（例如whsec_xxx）（/!\注意不要复制webhook id we_xxxx）。
6. 除了我们在部署期间早些时候设置的NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY和STRIPE_SECRET_KEY外，我们还需要将webhook密钥添加为STRIPE_WEBHOOK_SECRET环境变量。

使用新的环境变量重新部署

为了使新设置的环境变量生效并使所有内容正确协同工作，我们需要在Vercel中重新部署我们的应用。在您的Vercel仪表板中，导航到部署，点击溢出菜单按钮并选择"重新部署"（不要启用"使用现有构建缓存"选项）。一旦Vercel重新构建并重新部署了您的应用，您就可以设置您的产品和价格了。

创建产品和定价信息

您的应用程序的webhook监听Stripe上的产品更新，并自动将它们传播到您的Supabase数据库。因此，在您的webhook监听器运行的情况下，您现在可以在Stripe仪表板中创建您的产品和定价信息。

Stripe Checkout目前支持在特定间隔内收取预定金额的定价。尚不支持更复杂的计划（例如，不同的定价层或席位）。

例如，您可以创建具有不同定价层的商业模型，例如：

• 产品1：业余爱好
  • 价格1：每月10美元
  • 价格2：每年100美元
• 产品2：自由职业者
  • 价格1：每月20美元
  • 价格2：每年200美元

可选地，为了加快设置速度，我们添加了一个fixture文件，用于在您的Stripe账户中引导测试产品和定价数据。Stripe CLI fixtures命令执行此JSON文件中定义的一系列API请求。只需运行stripe fixtures fixtures/stripe-fixtures.json即可。

**重要提示：**确保您已正确配置Stripe webhook并使用所有必需的环境变量重新部署。

配置Stripe客户门户

1. 在设置中设置您的自定义品牌
2. 配置客户门户设置
3. 打开"允许客户更新他们的支付方式"
4. 打开"允许客户更新订阅"
5. 打开"允许客户取消订阅"
6. 添加您想要的产品和价格
7. 设置所需的业务信息和链接

就是这样

我知道，这确实需要完成很多步骤，但这是值得的。现在您已经准备好从客户那里赚取经常性收入了。🥳

本地开发

如果您还没有这样做，请将您的Github仓库克隆到本地机器上。

安装依赖

确保您已安装pnpm，然后运行：

pnpm install

接下来，使用Vercel CLI链接您的项目：

pnpm dlx vercel login
pnpm dlx vercel link

pnpm dlx从注册表运行包，无需将其安装为依赖项。或者，您可以全局安装这些包，并省略pnpm dlx部分。

如果您不打算使用本地Supabase实例进行开发和测试，可以使用Vercel CLI下载开发环境变量：

pnpm dlx vercel env pull .env.local

运行此命令将在您的项目文件夹中创建一个新的.env.local文件。出于安全考虑，您需要从Supabase仪表板（Settings > API）手动设置SUPABASE_SERVICE_ROLE_KEY。如果您不使用本地Supabase实例，还应该在package.json中的supabase:generate-types脚本中将--local标志更改为--linked或--project-id <string>。（参见-> [https://supabase.com/docs/reference/cli/supabase-gen-types-typescript]）

使用Supabase进行本地开发

强烈建议使用本地Supabase实例进行开发和测试。我们在package.json中提供了一组自定义命令。

首先，您需要安装Docker。您还应该复制或重命名：

• .env.local.example -> .env.local
• .env.example -> .env 接下来，运行以下命令来启动本地 Supabase 实例并执行迁移以设置数据库架构：

pnpm supabase:start

终端输出将为您提供访问 Supabase 堆栈中不同服务的 URL。Supabase Studio 是您可以对本地数据库实例进行更改的地方。

复制 service_role_key 的值，并将其粘贴为 .env.local 文件中 SUPABASE_SERVICE_ROLE_KEY 的值。

您可以随时使用以下命令打印出这些 URL：

pnpm supabase:status

要将本地 Supabase 实例链接到您的项目，请运行以下命令，导航到您上面创建的 Supabase 项目，并输入您的数据库密码。

pnpm supabase:link

如果您需要重置数据库密码，请前往您的数据库设置并点击"重置数据库密码"，这次请将其复制到密码管理器中！😄

🚧 警告：这将我们的本地开发实例链接到我们用于"生产"的项目。目前，它只包含测试记录，但一旦包含客户数据，我们建议使用分支或手动创建单独的"预览"或"测试"环境，以确保您的客户数据不会在本地使用，并且可以在部署到"生产"环境之前彻底测试架构更改/迁移。

一旦您链接了项目，您可以使用以下命令从远程数据库拉取任何架构更改：

pnpm supabase:pull

您可以使用以下命令用远程数据库中添加的任何数据为本地数据库填充种子数据：

pnpm supabase:generate-seed
pnpm supabase:reset

🚧 警告：这是从"生产"数据库填充种子数据。目前，这只包含测试数据，但一旦包含真实客户数据，我们建议使用分支或手动设置"预览"或"测试"环境。

您可以在本地 Supabase Studio 中对数据库架构进行更改，并运行以下命令生成与您的架构匹配的 TypeScript 类型：

pnpm supabase:generate-types

您还可以使用以下命令自动生成包含您对本地数据库架构所做所有更改的迁移文件：

pnpm supabase:generate-migration

并使用以下命令将这些更改推送到远程数据库：

pnpm supabase:push

请记住在部署到"生产"环境之前，在"本地"和"测试"或"预览"环境中彻底测试您的更改！

使用 Stripe CLI 测试 Webhooks

使用 Stripe CLI 登录您的 Stripe 账户：

pnpm stripe:login

这将打印一个 URL，供您在浏览器中导航并访问您的 Stripe 账户。

接下来，启动本地 webhook 转发：

pnpm stripe:listen

运行这个 Stripe 命令将在控制台打印一个 webhook 密钥（如 whsec_***）。在您的 .env.local 文件中将 STRIPE_WEBHOOK_SECRET 设置为这个值。如果您还没有设置，也应该使用 Stripe 仪表板中的测试模式（！）密钥在 .env.local 文件中设置 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY 和 STRIPE_SECRET_KEY。

运行 Next.js 客户端

在另一个终端中，运行以下命令启动开发服务器：

pnpm dev

请注意，webhook 转发和开发服务器必须在两个独立的终端中同时运行，应用程序才能正常工作。

最后，在浏览器中导航到 http://localhost:3000 查看渲染的应用程序。

上线

归档测试产品

在上线之前，归档所有测试模式的 Stripe 产品。在创建生产模式产品之前，请确保按照以下步骤设置生产模式环境变量和 webhooks。

配置生产环境变量

要在生产模式下运行项目并使用 Stripe 处理付款，请将 Stripe 从"测试模式"切换到"生产模式"。您的 Stripe API 密钥在生产模式下会有所不同，您还需要创建一个单独的生产模式 webhook。复制这些值并将它们粘贴到 Vercel 中，替换测试模式的值。

重新部署

之后，您需要重新构建生产部署以使更改生效。在项目仪表板中，导航到"部署"选项卡，选择最近的部署，点击溢出菜单按钮（在"访问"按钮旁边），然后选择"重新部署"（不要启用"使用现有构建缓存"选项）。

要验证您是否在生产模式下运行，请使用 Stripe 测试卡 测试结账。测试卡不应该能够使用。