跳转到主要内容

​
概述

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

​
特性

  • 快速设置 - 5 分钟内即可开始
  • 付款集成 - 使用 @dodopayments/nextjs 预配置的结账流程
  • 现代化界面 - 使用 Tailwind CSS 的简洁深色定价页面
  • Webhook 处理 - 可即刻使用的支付事件 webhook 端点
  • 客户门户 - 一键订阅管理
  • TypeScript - 完全类型化，类型精简聚焦
  • 预填充结账 - 演示如何传递客户数据以提升用户体验

​
先决条件

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

​
快速开始

1

Clone the Repository

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

Install Dependencies

npm install
3

Get API Credentials

在 Dodo Payments 注册并从仪表板获取凭据：
开发期间请确保处于 测试模式！
4

Configure Environment Variables

在根目录创建 .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

Add Your Products

使用你在 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

Run the Development Server

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: "john@example.com",
},

​
更新客户门户

在 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 仪表板中存在
  • .env 中的 API 密钥或环境设置错误
  • 检查浏览器控制台和终端中的错误
为了本地测试，请使用 ngrok 暴露你的服务器：
ngrok http 3000
在你的 Dodo dashboard 中将 webhook URL 更新为 ngrok URL。记得用正确的 webhook 验证密钥更新你的 .env 文件。

​
了解更多

​
支持

需要有关模板的帮助吗？