> ## 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.

# Astro 最小化模板

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

## 概述

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

<Info>
  这个样板项目使用 Astro 5、TypeScript、Tailwind CSS 4 和 `@dodopayments/astro` 适配器。
</Info>

### 特性

* **Quick Setup** - 在 5 分钟内开始
* **Payment Integration** - 使用 `@dodopayments/astro` 的预配置结账流程
* **Modern UI** - 使用 Tailwind CSS 的清爽暗色定价页面
* **Webhook Handler** - 可直接使用的支付事件 webhook 端点
* **Customer Portal** - 一键订阅管理
* **TypeScript** - 使用精简、聚焦的类型定义，完全类型化
* **Pre-filled Checkout** - 演示如何传递客户数据以提升用户体验

## 先决条件

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

* **Node.js LTS 版本**（Astro 5 所需）
* **Dodo Payments 账户**（从仪表板访问 API 和 Webhook 密钥）

## 快速开始

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
    cd dodo-astro-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:4321/
    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:4321](http://localhost:4321) 查看您的定价页面！
  </Step>
</Steps>

## 项目结构

```text theme={null}
src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind
```

## 自定义

### 更新产品信息

编辑 `src/lib/products.ts` 可修改：

* 产品 ID（来自 Dodo 仪表板）
* 价格
* 功能
* 描述

### 预填充客户数据

在 `src/components/ProductCard.astro` 中，将硬编码值替换为您的实际用户数据：

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

### 更新客户门户

在 `src/components/Header.astro` 中，将硬编码的客户 ID 替换为来自您的认证系统或数据库的实际客户 ID：

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

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

## Webhook 事件

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

* `onSubscriptionActive` - 在订阅变为活跃时触发
* `onSubscriptionCancelled` - 在订阅取消时触发

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

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

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

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

## 部署

此模板使用静态输出和按需渲染的 API 路由。您需要为您的部署平台安装一个适配器：

| 平台         | 指南                                                                      |
| ---------- | ----------------------------------------------------------------------- |
| Vercel     | [部署到 Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [部署到 Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [部署到 Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

请参阅 [Astro 的部署指南](https://docs.astro.build/en/guides/deploy/) 以获取所有平台的信息。

### 更新 Webhook URL

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

```text theme={null}
https://your-domain.com/api/webhook
```

还请记得在生产环境中更新 `DODO_PAYMENTS_WEBHOOK_KEY` 环境变量，使其与已部署域名的 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 4321
    ```

    在 [Dodo 仪表板](https://app.dodopayments.com/developer/webhooks) 中将 webhook URL 更新为 ngrok URL。别忘了在 .env 文件中更新正确的 webhook 验证密钥。
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    在 `src/components/Header.astro` 中将硬编码的 `CUSTOMER_ID` 替换为来自 Dodo 仪表板的实际客户 ID。

    或者整合您的认证系统和数据库，动态获取客户 ID。
  </Accordion>

  <Accordion title="Build fails with adapter error">
    该样板使用静态输出结合按需 API 路由。部署时需要安装适配器：

    详见 [Astro 的部署指南](https://docs.astro.build/en/guides/deploy/) 获取详细信息。
  </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-astro-minimal-boilerplate) 以获取问题和更新
* 联系我们的 [支持团队](mailto:support@dodopayments.com) 寻求帮助