Astro 最小化模板

概述

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

此 boilerplate 使用 Astro 5、TypeScript、Tailwind CSS 4 和 @dodopayments/astro adaptor。要将相同的 API routes 添加到现有 app，请参阅 Astro 适配器。

特性

此 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。

快速开始

Clone the Repository

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

Install Dependencies

npm install

Get API Credentials

在 Dodo Payments 注册，然后从 dashboard 获取 credentials：

API Key： 在 Dashboard → Developer → API Keys 下创建 key。
Webhook Key： 在 Dashboard → Developer → Webhooks 下添加 endpoint，然后复制其 signing secret。Endpoint URL 必须公开并使用 HTTPS。要在你的计算机上接收 events，请参阅 Webhook Events。

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

Configure Environment Variables

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

cp .env.example .env

将值设置为你的 Dodo Payments credentials：

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。

不要将 .env 文件提交到 version control。Repository 中的 .gitignore 已将其排除。

Add Your Products

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

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 与其保持同步。

Run the Development Server

npm run dev

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

项目结构

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

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。将其替换为已登录用户的信息：

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：

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：

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

要处理更多 events，请添加相应的 handlers，例如 onPaymentSucceeded。Astro 适配器列出了所有受支持的 handlers。 Dodo Payments 无法访问 localhost。在本地开发时，使用 ngrok 等 tunnel 暴露本地 server，并将 tunnel URL 用作 webhook endpoint。

部署

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

Platform	Guide
Vercel	部署到 Vercel
Netlify	部署到 Netlify
Cloudflare	部署到 Cloudflare

其他 platforms 请参阅 Astro 的部署指南。在你的 hosting platform 中添加四个 environment variables，并将 DODO_PAYMENTS_RETURN_URL 设置为 production URL。

更新 Webhook URL

部署后，在 Dodo Payments Dashboard 中添加 production webhook URL：

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：

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 暴露你的 server：

ngrok http 4321

在你的 Dodo dashboard 中，使用 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 的部署指南。

了解更多

Dodo Payments 文档
Checkout Sessions 文档
Webhooks 文档
Astro 适配器：Checkout、CustomerPortal 和 Webhooks handlers 的选项
Astro 文档

支持

如需 boilerplate 方面的帮助：

在 Discord 社区中提问。
在 GitHub repository 中报告问题并关注更新。
发送邮件联系 support team。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

概述

特性

前置条件

快速开始

项目结构

自定义

更新 Product 信息

预填充 Customer 数据

更新 Customer Portal

Webhook Events

部署

更新 Webhook URL

故障排除

了解更多

支持

​概述

​特性

​前置条件

​快速开始

​项目结构

​自定义

​更新 Product 信息

​预填充 Customer 数据

​更新 Customer Portal

​Webhook Events

​部署

​更新 Webhook URL

​故障排除

​了解更多

​支持

概述

特性

前置条件

快速开始

项目结构

自定义

更新 Product 信息

预填充 Customer 数据

更新 Customer Portal

Webhook Events

部署

更新 Webhook URL

故障排除

了解更多

支持