# Astro 整合指南 (/guides/frameworks/astro)
Astro 是一個內容優先的現代框架，支援 Islands Architecture 和多種渲染模式。Recur 提供官方 Astro adapter，讓你只需幾行程式碼就能整合訂閱功能。
前置需求 [#前置需求]
Astro 預設是靜態網站生成（SSG），如果需要使用 Server SDK 功能（如 Customer Portal、Webhook），你需要啟用 Server 模式並安裝 adapter。
安裝 [#安裝]
官方 Astro adapter 提供最簡潔的整合方式：
```bash
npm install @recur-tw/astro
```
`@recur-tw/astro` 提供預封裝的 handler 函數，大幅減少 boilerplate 程式碼。
如果你需要更多自訂彈性，可以直接使用核心 SDK：
```bash
npm install recur-tw
```
設定輸出模式 [#設定輸出模式]
在 `astro.config.mjs` 中設定：
全伺服器模式，所有頁面和 API 都在伺服器執行：
```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel'; // 或其他 adapter
export default defineConfig({
output: 'server',
adapter: vercel(),
});
```
如果想讓部分頁面預先渲染（例如首頁），在該頁面加入 `export const prerender = true;`
預設靜態，只有 API routes 需要伺服器執行：
```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
adapter: node({ mode: 'standalone' }),
});
```
在需要伺服器執行的 API 檔案中加入：
```typescript
export const prerender = false;
```
純靜態網站，只能使用前端功能：
```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
// 不需要設定 output，預設就是 static
});
```
靜態模式無法使用 Server SDK。如需 Customer Portal 或 Webhook，需要另外建立後端。
設定環境變數 [#設定環境變數]
在 `.env` 中加入：
```bash
# 前端使用（可公開）
PUBLIC_RECUR_PUBLISHABLE_KEY=pk_test_xxx
# 後端使用（保密）
RECUR_SECRET_KEY=sk_test_xxx
RECUR_WEBHOOK_SECRET=whsec_xxx
```
結帳功能 [#結帳功能]
方法 1：使用 Adapter（推薦） [#方法-1使用-adapter推薦]
建立 Checkout Endpoint [#建立-checkout-endpoint]
```typescript
// src/pages/api/checkout.ts
import { Checkout } from '@recur-tw/astro';
export const prerender = false;
// 使用 process.env 確保在 Vercel 等平台上正確讀取環境變數
const secretKey = process.env.RECUR_SECRET_KEY || import.meta.env.RECUR_SECRET_KEY;
export const GET = Checkout({
secretKey,
successUrl: '/success?session_id={CHECKOUT_SESSION_ID}',
cancelUrl: '/pricing',
locale: 'zh-TW',
});
```
在頁面中使用 [#在頁面中使用]
```astro
---
// src/pages/pricing.astro
---
選擇你的方案
```
`customerEmail` 和 `customerName` 都是選填。如果未預填，用戶會在結帳頁面輸入（Email 在結帳時為必填，用於寄送收據）。
支援的 Query Parameters：
| 參數 | 說明 | 必填 |
| --------------- | --------------------- | :-: |
| `productId` | 產品 ID | ✓\* |
| `productSlug` | 產品 slug（替代 productId） | ✓\* |
| `customerEmail` | 預填客戶 Email | |
| `customerName` | 預填客戶姓名 | |
| `customerId` | 現有客戶 ID | |
| `metadata` | URL-encoded JSON 字串 | |
\*
`productId`
或
`productSlug`
至少需提供一個
方法 2：自訂 Resolver [#方法-2自訂-resolver]
如果你需要從認證系統取得客戶資訊：
```typescript
// src/pages/api/checkout.ts
import { Checkout } from '@recur-tw/astro';
import { getSession } from '@/lib/auth';
export const prerender = false;
export const GET = Checkout({
secretKey: import.meta.env.RECUR_SECRET_KEY,
successUrl: '/success',
resolver: async (context) => {
const session = await getSession(context.request);
return {
customerEmail: session?.user?.email,
customerName: session?.user?.name,
customerId: session?.user?.recurCustomerId,
};
},
});
```
方法 3：純 Astro（無 Adapter） [#方法-3純-astro無-adapter]
使用 `