5分钟快速上手Next.js billing app：Lemon Squeezy订阅系统搭建教程

【免费下载链接】nextjs-billingNext.js billing app with Lemon Squeezy项目地址: https://gitcode.com/gh_mirrors/ne/nextjs-billing

Next.js billing app是一款基于Next.js 14构建的订阅制SaaS应用模板，集成了Lemon Squeezy支付系统，可帮助开发者快速搭建专业的订阅管理平台。本教程将带你在5分钟内完成从环境配置到系统部署的全流程，轻松实现订阅功能集成。

🌟 为什么选择Next.js + Lemon Squeezy组合？

这款模板采用现代化技术栈，专为订阅制应用设计：

• 框架：Next.js 14提供卓越的性能和开发体验
• 支付处理：Lemon Squeezy简化订阅管理和支付流程
• 认证系统：集成GitHub OAuth实现安全登录
• 数据存储：Neon + Drizzle ORM提供无服务器Postgres解决方案
• UI组件：使用Wedges组件库打造专业界面

🚀 快速开始：5分钟安装步骤

1️⃣ 克隆项目仓库

首先将项目代码克隆到本地环境：

git clone https://gitcode.com/gh_mirrors/ne/nextjs-billing cd nextjs-billing

2️⃣ 安装依赖包

使用pnpm安装项目所需依赖：

pnpm install

3️⃣ 配置环境变量

复制环境变量模板并填写必要信息：

cp .env.example .env

需要配置的核心参数包括：

# Lemon Squeezy配置 LEMONSQUEEZY_API_KEY=your_api_key LEMONSQUEEZY_STORE_ID=your_store_id LEMONSQUEEZY_WEBHOOK_SECRET=random_secret # 数据库配置 POSTGRES_URL=your_neon_postgres_url # 认证配置 AUTH_GITHUB_ID=your_github_oauth_id AUTH_GITHUB_SECRET=your_github_oauth_secret AUTH_SECRET=random_auth_secret

4️⃣ 初始化数据库

运行以下命令初始化数据库结构：

pnpm db:push

5️⃣ 启动开发服务器

一切准备就绪，启动开发服务器：

pnpm dev

访问 http://localhost:3000 即可看到应用界面！

🔑 关键配置详解

Lemon Squeezy账户设置

1. 访问Lemon Squeezy注册页面创建账户
2. 在测试模式下，前往Settings > API创建API密钥
3. 从Settings > Stores获取商店ID
4. 生成随机字符串作为webhook密钥

数据库连接

本项目使用Neon提供的无服务器Postgres数据库：

1. 注册Neon账户并创建数据库
2. 从Neon控制台获取连接URL
3. 将URL填入POSTGRES_URL环境变量

认证配置

GitHub OAuth设置：

1. 创建GitHub OAuth应用
2. 获取Client ID和Client Secret
3. 生成32位随机字符串作为AUTH_SECRET：

openssl rand -hex 32

🔄 配置Webhook接收支付事件

Webhook是接收Lemon Squeezy支付事件的关键：

1. 在应用仪表盘中点击"Setup webhook"按钮自动配置
2. 或手动在Lemon Squeezy的Settings > Webhooks添加webhook URL
3. 确保勾选subscription_created和subscription_updated事件
4. 填入与环境变量相同的webhook密钥

应用的webhook处理端点位于/api/webhook，负责接收并处理支付事件。

📦 核心功能模块

订阅管理

应用提供完整的订阅生命周期管理：

• 查看当前订阅状态
• 更改订阅计划
• 暂停/恢复订阅
• 取消订阅

相关代码位于src/components/dashboard/billing/subscription/目录，包括：

• subscriptions.tsx：订阅状态展示
• actions.tsx：订阅管理操作
• change-plans.tsx：计划变更界面

产品计划展示

产品计划展示模块位于src/components/dashboard/billing/plans/，主要文件包括：

• plans.tsx：计划列表组件
• plan.tsx：单个计划卡片
• change-plan-button.tsx：切换计划按钮

📝 上线前检查清单

准备部署到生产环境时，请完成以下步骤：

1. 在Lemon Squeezy后台关闭测试模式
2. 创建生产环境API密钥并更新环境变量
3. 配置生产环境webhook
4. 确保所有环境变量正确设置
5. 运行数据库迁移：pnpm db:push

💡 实用提示

• 使用Drizzle Studio管理数据库：pnpm db:studio
• 开发环境需要使用ngrok或LocalCan创建公网URL接收webhook
• Lemon Squeezy提供内置的Customer Portal，可作为订阅管理的替代方案
• 应用采用Next.js App Router架构，支持组件级数据获取

通过本教程，你已经掌握了Next.js billing app的基本搭建流程。这个模板提供了坚实的基础，你可以在此之上构建更复杂的订阅功能，打造属于自己的SaaS产品！

【免费下载链接】nextjs-billingNext.js billing app with Lemon Squeezy项目地址: https://gitcode.com/gh_mirrors/ne/nextjs-billing