> ## 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 minimal boilerplate，即可获得定价页面、checkout sessions、webhook handler，以及已连接到 Dodo Payments 的 Customer Portal 链接。

## 概述

Astro minimal boilerplate 是一个已连接 Dodo Payments 的 starter app。添加 API keys 和 product IDs 后，你就能获得一个可打开 checkout 的定价页面、一个用于处理 payment events 的 webhook endpoint，以及一个指向 Customer Portal 的链接。

> [!NOTE]
>
> 此 boilerplate 使用 Astro 5、TypeScript、Tailwind CSS 4 和 `@dodopayments/astro` adaptor。要将相同的 API routes 添加到现有 app，请参阅 [Astro 适配器](/developer-resources/astro-adaptor)。

### 特性

此 boilerplate 包含：

* **快速设置**：大约五分钟内即可从克隆项目到运行定价页面。
* **Checkout**：基于 `@dodopayments/astro` 构建的预配置 checkout flow。
* **定价页面**：使用 Tailwind CSS 样式化的深色主题定价页面。
* **Webhook Handler**：验证每个 webhook signature，并为 event 运行你的代码的 endpoint。
* **Customer Portal**：打开 Customer Portal 的 header 链接，客户可以在其中管理自己的 subscriptions。
* **TypeScript**：带类型的 product definitions 和 handlers。
* **预填充 Checkout**：将客户的姓名和 email 传递给 checkout，客户无需重新输入。

## 前置条件

开始之前，你需要：

* **Node.js LTS 版本**，这是 Astro 5 的要求。
* **Dodo Payments 账户**，用于在 dashboard 中创建 API key 和 webhook signing secret。

## 快速开始

**1. Clone the Repository**

```bash theme={null}
git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
```

**2. Install Dependencies**

```bash theme={null}
npm install
```

**3. Get API Credentials**

在 [Dodo Payments](https://dodopayments.com/) 注册，然后从 dashboard 获取 credentials：

* **API Key：** 在 [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys) 下创建 key。
* **Webhook Key：** 在 [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks) 下添加 endpoint，然后复制其 signing secret。Endpoint URL 必须公开并使用 HTTPS。要在你的计算机上接收 events，请参阅 [Webhook Events](#webhook-events)。

> [!TIP]
>
> 在侧边栏中的 **Live Mode** 开关关闭时创建两者。Test mode key 只能与 `DODO_PAYMENTS_ENVIRONMENT=test_mode` 一起使用，且 test mode payments 不会转移真实资金。

**4. Configure Environment Variables**

复制示例文件，在根目录中创建一个 `.env` 文件：

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

将值设置为你的 Dodo Payments credentials：

```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
```

`.env.example` 将 `DODO_PAYMENTS_RETURN_URL` 设置为端口 `3000`。将其更改为 `4321`，即 Astro dev server 使用的端口，以便 checkout 在完成后将客户返回到你的 app。

API routes 会读取以下 variables：

* `DODO_PAYMENTS_API_KEY` 用于验证 checkout 和 Customer Portal routes。
* `DODO_PAYMENTS_WEBHOOK_KEY` 用于验证 webhook signatures。
* `DODO_PAYMENTS_RETURN_URL` 是 checkout 在 payment 后将客户发送到的位置。
* `DODO_PAYMENTS_ENVIRONMENT` 是 `test_mode` 或 `live_mode`。

> [!WARNING]
>
> 不要将 `.env` 文件提交到 version control。Repository 中的 `.gitignore` 已将其排除。

**5. Add Your Products**

将 `src/lib/products.ts` 中的示例 products 替换为你自己的 products。将每个 `product_id` 设置为 dashboard 中 **Products** 下某个 product 的 ID：

```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
];
```

定价页面会从此文件中显示 `name`、`description`、`price` 和 `features`。Checkout 会收取 Dodo Payments 中 product 设置的价格，因此请确保 `price` 与其保持同步。

**6. Run the Development Server**

```bash theme={null}
npm run dev
```

打开 [http://localhost:4321](http://localhost:4321) 查看你的定价页面。

## 项目结构

Checkout、Customer Portal 和 webhook API routes 位于 `src/pages/api/` 下：

```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
```

## 自定义

### 更新 Product 信息

编辑 `src/lib/products.ts` 以更改：

* Product IDs，来自 Dodo Payments dashboard 中的 **Products**
* Prices
* Features
* Descriptions

### 预填充 Customer 数据

`src/components/ProductCard.astro` 中的 checkout script 会在每个 checkout request 中发送硬编码的姓名和 email。将其替换为已登录用户的信息：

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

### 更新 Customer Portal

`src/components/Header.astro` 中的 **Customer Portal** 链接会打开 `/api/customer-portal`，其中使用了硬编码的 customer ID。将其替换为 authentication system 或 database 中的 customer ID：

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

要获取用于测试的 customer ID，请完成一次 test purchase，然后从 dashboard 的 **Customers** 中复制客户的 ID。

## Webhook Events

`src/pages/api/webhook.ts` 中的 handler 会使用 `DODO_PAYMENTS_WEBHOOK_KEY` 验证每个 request，然后处理两个 events：

* `onSubscriptionActive` 在 subscription 变为 active 时运行（`subscription.active`）。
* `onSubscriptionCancelled` 在 subscription 被 cancelled 时运行（`subscription.cancelled`）。

在这些 handlers 中添加你的 business logic：

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

要处理更多 events，请添加相应的 handlers，例如 `onPaymentSucceeded`。[Astro 适配器](/developer-resources/astro-adaptor#supported-webhook-event-handlers) 列出了所有受支持的 handlers。

Dodo Payments 无法访问 `localhost`。在本地开发时，使用 [ngrok](https://ngrok.com/) 等 tunnel 暴露本地 server，并将 tunnel URL 用作 webhook endpoint。

## 部署

Astro 会将页面构建为 static output，每个 API route 都会设置 `export const prerender = false`，以便按需渲染。按需 routes 需要适用于你的 deployment platform 的 Astro adapter：

| Platform | Guide |
| - | - |
| 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/) |

其他 platforms 请参阅 [Astro 的部署指南](https://docs.astro.build/en/guides/deploy/)。在你的 hosting platform 中添加四个 environment variables，并将 `DODO_PAYMENTS_RETURN_URL` 设置为 production URL。

### 更新 Webhook URL

部署后，在 [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks) 中添加 production webhook URL：

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

每个 endpoint 都有自己的 signing secret。将 production environment 中的 `DODO_PAYMENTS_WEBHOOK_KEY` 设置为此 endpoint 的 signing secret。

## 故障排除

> **Module not found or build errors**
>
> 删除 `node_modules` 和 `package-lock.json`，然后重新安装 dependencies：
>
> ```bash theme={null}
> rm -rf node_modules package-lock.json
> npm install
> ```

> **Checkout redirect fails**
>
> 检查以下常见原因：
>
> * Product ID 不存在于你的 Dodo Payments dashboard 中。
> * `.env` 中的 API key 或 `DODO_PAYMENTS_ENVIRONMENT` 错误。Test mode key 只能与 `test_mode` 一起使用。
>
> 在 browser console 和运行 `npm run dev` 的 terminal 中查找 error。

> **Webhooks not receiving events**
>
> 要进行本地测试，请使用 [ngrok](https://ngrok.com) 暴露你的 server：
>
> ```bash theme={null}
> ngrok http 4321
> ```
>
> 在你的 [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) 中，使用 ngrok HTTPS URL 后跟 `/api/webhook` 添加 endpoint。将该 endpoint 的 signing secret 复制到 `.env` 文件中的 `DODO_PAYMENTS_WEBHOOK_KEY`。

> **Customer portal link doesn't work**
>
> 将 `src/components/Header.astro` 中硬编码的 `CUSTOMER_ID` 替换为 Dodo Payments dashboard 中某个客户的 ID。
>
> 在 production 中，应改为从 authentication system 和 database 获取 customer ID。

> **Build fails with adapter error**
>
> API routes 会按需渲染，而 repository 不包含 deployment adapter。在构建 production 版本之前，请安装适用于你平台的 Astro adapter。
>
> 详情请参阅 [Astro 的部署指南](https://docs.astro.build/en/guides/deploy/)。

## 了解更多

* [Dodo Payments 文档](https://docs.dodopayments.com/)
* [Checkout Sessions 文档](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks 文档](https://docs.dodopayments.com/developer-resources/webhooks)
* [Astro 适配器](/developer-resources/astro-adaptor)：`Checkout`、`CustomerPortal` 和 `Webhooks` handlers 的选项
* [Astro 文档](https://docs.astro.build/)

## 支持

如需 boilerplate 方面的帮助：

* 在 [Discord 社区](https://discord.gg/bYqAp4ayYh) 中提问。
* 在 [GitHub repository](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) 中报告问题并关注更新。
* 发送邮件联系 [support team](mailto:support@dodopayments.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.