跳转到主要内容

​
概述

Next.js 最小化模板提供了一个现成的起点，用于将 Dodo Payments 集成到您的 Next.js 应用程序中。此模板包括结账会话、Webhook 处理、客户门户和现代 UI 组件，帮助您快速开始接受付款。
此模板使用 Next.js 16 应用路由器，配合 TypeScript、Tailwind CSS 4 和 @dodopayments/nextjs 适配器。

​
特性

  • 快速设置 - 在 5 分钟内开始
  • 支付集成 - 使用 @dodopayments/nextjs 预配置的结账流程
  • 现代 UI - 干净、深色主题的定价页面，使用 Tailwind CSS
  • Webhook 处理程序 - 准备好的支付事件 Webhook 端点
  • 客户门户 - 一键订阅管理
  • TypeScript - 完全类型化，具有最小、专注的类型
  • 预填充结账 - 演示传递客户数据以改善用户体验

​
先决条件

在开始之前，请确保您拥有：
  • Node.js 20.9+（Next.js 16 所需）
  • Dodo Payments 账户（从仪表板访问 API 和 Webhook 密钥）

​
快速开始

1

克隆仓库

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate
2

安装依赖

npm install
3

获取 API 凭证

在 Dodo Payments 注册并从仪表板获取您的凭证：
在开发时确保您处于 测试模式！
4

配置环境变量

在根目录中创建一个 .env 文件：
cp .env.example .env
使用您的 Dodo Payments 凭证更新值：
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode
切勿将您的 .env 文件提交到版本控制。它已包含在 .gitignore 中。
5

添加您的产品

使用您在 Dodo Payments 中的实际产品 ID 更新 src/lib/products.ts：
export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];
6

运行开发服务器

npm run dev
打开 http://localhost:3000 查看您的定价页面！

​
项目结构

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

​
自定义

​
更新产品信息

编辑 src/lib/products.ts 以修改：
  • 产品 ID（来自您的 Dodo 仪表板）
  • 定价
  • 特性
  • 描述

​
预填充客户数据

在 src/app/components/ProductCard.tsx 中，将硬编码的值替换为您的实际用户数据： 
customer: {
  name: "John Doe",
  email: "[email protected]",
},

​
更新客户门户

在 src/app/components/Header.tsx 中，替换硬编码的客户 ID： 
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
您可以完成一次测试购买以获取测试的客户 ID。

​
Webhook 事件

该模板演示了在 src/app/api/webhook/route.ts 中处理两个 Webhook 事件：
  • onSubscriptionActive - 当订阅变为活动时触发
  • onPaymentSucceeded - 当支付成功时触发
在这些处理程序中添加您的业务逻辑： 
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
根据需要添加更多 Webhook 事件。 对于本地开发，您可以使用 ngrok 创建一个安全的隧道到您的本地服务器，并将其用作您的 Webhook URL。

​
部署

​
为生产构建

npm run build
npm start

​
部署到 Vercel

[ 使用 Vercel 部署 ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) 不要忘记在 Vercel 仪表板中添加您的环境变量！

​
更新 Webhook URL

部署后，在 Dodo Payments 仪表板 中更新您的 Webhook URL： 
https://example.com/api/webhook

​
故障排除

删除 node_modules 并重新安装依赖：
rm -rf node_modules package-lock.json
npm install
常见原因：
  • 无效的产品 ID - 验证它是否存在于您的 Dodo 仪表板中
  • 错误的 API 密钥或 .env 中的环境设置
  • 检查浏览器控制台和终端中的错误
对于本地测试，使用 ngrok 来暴露您的服务器：
ngrok http 3000
在您的 Dodo 仪表板 中将 Webhook URL 更新为 ngrok URL。记得用正确的 Webhook 验证密钥更新您的 .env 文件。
在 src/app/components/Header.tsx 中，将硬编码的 CUSTOMER_ID 替换为来自您的 Dodo 仪表板的实际客户 ID。或者集成您的身份验证系统和数据库以动态获取客户 ID。

​
了解更多

​
支持

需要有关模板的帮助吗？