跳转到主要内容

​
概述

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

​
快速开始

1

Clone the Repository

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

Install Dependencies

npm install
3

Get API Credentials

在 Dodo Payments 注册，然后在仪表板中获取凭据：
开发过程中请确保处于 测试模式！
4

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 中。
5

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

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 签名密钥相匹配。

​
故障排除

删除 node_modules 并重新安装依赖项：
rm -rf node_modules package-lock.json
npm install
常见原因：
  • 无效的产品 ID - 请确认它在您的 Dodo 仪表板中存在
  • .env 中的 API 密钥或环境设置错误
  • 查看浏览器控制台和终端的错误
本地测试时，可使用 ngrok 将服务器暴露出来：
ngrok http 4321
在 Dodo 仪表板 中将 webhook URL 更新为 ngrok URL。别忘了在 .env 文件中更新正确的 webhook 验证密钥。
该样板使用静态输出结合按需 API 路由。部署时需要安装适配器：详见 Astro 的部署指南 获取详细信息。

​
了解更多

​
支持

需要有关模板的帮助吗？