> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js 最小化模板

> 使用我们的最小化 Next.js 模板快速开始将 Dodo Payments 集成到您的 Next.js 应用程序中

## 概述

Next.js 最小化模板提供了一个现成的起点，用于将 Dodo Payments 集成到您的 Next.js 应用程序中。此模板包括结账会话、Webhook 处理、客户门户和现代 UI 组件，帮助您快速开始接受付款。

<Info>
  这个样板工程使用 Next.js 16 App Router、TypeScript、Tailwind CSS 4 以及 `@dodopayments/nextjs` 适配器。
</Info>

### 特性

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

## 先决条件

在开始之前，请确保您拥有：

* **Node.js 20.9+**（Next.js 16 所需）
* **Dodo Payments 账户**（从仪表板访问 API 和 Webhook 密钥）

## 快速开始

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    在 [Dodo Payments](https://dodopayments.com/) 注册并从仪表板获取凭据：

    * **API 密钥：** [仪表板 → 开发者 → API 密钥](https://app.dodopayments.com/developer/api-keys)
    * **Webhook 密钥：** [仪表板 → 开发者 → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      开发期间请确保处于 **测试模式**！
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    在根目录创建 `.env` 文件：

    ```bash theme={null}
    cp .env.example .env
    ```

    使用您的 Dodo Payments 凭证更新值：

    ```env theme={null}
    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
    ```

    <Warning>
      切勿将 `.env` 文件提交到版本控制。它已经包含在 `.gitignore` 中。
    </Warning>
  </Step>

  <Step title="Add Your Products">
    使用你在 Dodo Payments 上的实际产品 ID 更新 `src/lib/products.ts`：

    ```typescript theme={null}
    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
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    打开 [http://localhost:3000](http://localhost:3000) 查看你的定价页面！
  </Step>
</Steps>

## 项目结构

```text theme={null}
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` 中，用你的实际用户数据替换硬编码的值：

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### 更新客户门户

在 `src/app/components/Header.tsx` 中，用实际客户 ID 替换硬编码值：

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

您可以完成一次测试购买以获取测试的客户 ID。

## Webhook 事件

该样板示例展示了如何在 `src/app/api/webhook/route.ts` 中处理两个 webhook 事件：

* `onSubscriptionActive` - 当订阅变为激活状态时触发
* `onPaymentSucceeded` - 当付款成功时触发

在这些处理程序中添加您的业务逻辑：

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

根据需要添加更多 Webhook 事件。

对于本地开发，您可以使用 [ngrok](https://ngrok.com/) 创建一个安全的隧道到您的本地服务器，并将其用作您的 Webhook URL。

## 部署

### 为生产构建

```bash theme={null}
npm run build
npm start
```

### 部署到 Vercel

\[

![使用 Vercel 部署](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate))

不要忘记在 Vercel 仪表板中添加您的环境变量！

### 更新 Webhook URL

部署后，在 [Dodo Payments 仪表板](https://app.dodopayments.com/developer/webhooks) 中更新您的 Webhook URL：

```
https://example.com/api/webhook
```

## 故障排除

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    删除 `node_modules` 并重新安装依赖项：

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **常见原因：**

    * 无效的产品 ID —— 请确认它在你的 Dodo 仪表板中存在
    * `.env` 中的 API 密钥或环境设置错误
    * 检查浏览器控制台和终端中的错误
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    为了本地测试，请使用 [ngrok](https://ngrok.com) 暴露你的服务器：

    ```bash theme={null}
    ngrok http 3000
    ```

    在你的 [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) 中将 webhook URL 更新为 ngrok URL。记得用正确的 webhook 验证密钥更新你的 .env 文件。
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    在 `src/app/components/Header.tsx` 中，用你在 Dodo 仪表板上的实际客户 ID 替换硬编码的 `CUSTOMER_ID`。

    或者集成你的身份验证系统与数据库，以动态获取客户 ID。
  </Accordion>
</AccordionGroup>

## 了解更多

* [Dodo Payments 文档](https://docs.dodopayments.com/)
* [结账会话文档](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks 文档](https://docs.dodopayments.com/developer-resources/webhooks)

## 支持

需要有关模板的帮助吗？

* 加入我们的 [Discord 社区](https://discord.gg/bYqAp4ayYh) 进行提问和讨论
* 查看 [GitHub 仓库](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) 以获取问题和更新
* 联系我们的 [支持团队](mailto:support@dodopayments.com) 寻求帮助