Astro 最小化模板 - Dodo Payments Documentation

概述

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

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

特性

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 密钥）

快速开始

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 注册，然后在仪表板中获取凭据：

API 密钥： 仪表板 → 开发者 → API 密钥
Webhook 密钥： 仪表板 → 开发者 → Webhooks

开发过程中请确保处于 测试模式！

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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode

切勿将 .env 文件提交到版本控制。它已经包含在 .gitignore 中。

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

Run the Development Server

npm run dev

打开 http://localhost:4321 查看您的定价页面！

项目结构

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 中，将硬编码值替换为您的实际用户数据：

customer: {
  name: "John Doe",
  email: "john@example.com",
},

更新客户门户

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

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

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

Webhook 事件

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

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

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

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

根据需要添加更多 Webhook 事件。对于本地开发，您可以使用 ngrok 创建一个安全的隧道到您的本地服务器，并将其用作您的 Webhook URL。

部署

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

平台	指南
Vercel	部署到 Vercel
Netlify	部署到 Netlify
Cloudflare	部署到 Cloudflare

请参阅 Astro 的部署指南以获取所有平台的信息。

更新 Webhook URL

部署后，在 Dodo Payments 仪表板中更新您的 Webhook URL：

https://your-domain.com/api/webhook

还请记得在生产环境中更新 DODO_PAYMENTS_WEBHOOK_KEY 环境变量，使其与已部署域名的 webhook 签名密钥相匹配。

故障排除

Module not found or build errors

删除 node_modules 并重新安装依赖项：

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

常见原因：

无效的产品 ID - 请确认它在您的 Dodo 仪表板中存在
.env 中的 API 密钥或环境设置错误
查看浏览器控制台和终端的错误

Webhooks not receiving events

本地测试时，可使用 ngrok 将服务器暴露出来：

ngrok http 4321

在 Dodo 仪表板中将 webhook URL 更新为 ngrok URL。别忘了在 .env 文件中更新正确的 webhook 验证密钥。

Customer portal link doesn't work

在 src/components/Header.astro 中将硬编码的 CUSTOMER_ID 替换为来自 Dodo 仪表板的实际客户 ID。或者整合您的认证系统和数据库，动态获取客户 ID。

Build fails with adapter error

该样板使用静态输出结合按需 API 路由。部署时需要安装适配器：详见 Astro 的部署指南获取详细信息。

了解更多

支持

需要有关模板的帮助吗？

加入我们的 Discord 社区进行提问和讨论
查看 GitHub 仓库以获取问题和更新
联系我们的支持团队寻求帮助

​概述

​特性

​先决条件

​快速开始

​项目结构

​自定义

​更新产品信息

​预填充客户数据

​更新客户门户

​Webhook 事件

​部署

​更新 Webhook URL

​故障排除

​了解更多

​支持

概述

特性

先决条件

快速开始

项目结构

自定义

更新产品信息

预填充客户数据

更新客户门户

Webhook 事件

部署

更新 Webhook URL

故障排除

了解更多

支持