# SvelteKit 支付：完整集成指南

> 了解如何使用 Dodo Payments 为 SvelteKit 应用添加支付处理功能。本指南涵盖结账组件、服务端钩子、表单操作和订阅 Webhook 处理。
- **Author**: Ayush Agarwal
- **Published**: 2026-03-23
- **Category**: Payments, Developer Tools, How-To
- **URL**: https://dodopayments.com/blogs/zh/sveltekit-payments-integration

---

SvelteKit 凭借其简洁性和速度正在迅速普及。开发者喜欢直观的路由、强大的服务端渲染，以及客户端和服务端代码之间的无缝衔接。但说到支付，大多数指南仍然以 Stripe 为例。Stripe 虽然功能强大，却常常让开发者承担大量税务合规和监管工作。

下面介绍如何使用 MoR（名义商户）来完成支付集成。通过将 Dodo Payments 作为你的 MoR（名义商户），你可以获得更简单的集成体验，不再为税务问题头疼。Dodo Payments 会为你处理全球销售税、增值税和合规事务，让你专注于构建 SvelteKit 应用。

本指南将带你完整了解如何将 Dodo Payments 集成到 SvelteKit 应用中。我们会介绍从设置 SDK，到处理 Webhook，再到在 load 函数中检查订阅状态的全部流程。

## 为什么选择 SvelteKit + Dodo Payments？

SvelteKit 和 Dodo Payments 是现代 SaaS 开发的完美组合。Svelte 的响应式机制让结账组件简洁易管理。你不必仅仅为了显示加载指示器或处理结账事件，就引入复杂的状态管理库。

SvelteKit 的服务端钩子和 API 路由为处理 Webhook 提供了优雅的方式。你可以在安全的服务端环境中验证签名并处理支付事件，无需编写额外的样板代码。表单操作也非常适合触发支付，让你可以使用标准 HTML 表单和渐进增强来处理结账会话。

更重要的是，使用 Dodo Payments 这样的 MoR（名义商户），意味着你无需操心全球商业运营的复杂性。无论你销售的是一次性数字产品，还是周期性订阅，Dodo 都会在 220 多个国家和地区为你处理税费收取、缴纳和合规事务。对于希望从第一天起走向全球的小型团队和个人创业者来说，这是巨大的优势。

## 架构概览

在深入代码之前，我们先看看 Dodo Payments 如何融入 SvelteKit 架构。集成通常包括三个主要部分：客户端结账、服务端会话创建，以及 Webhook 处理程序。

```mermaid
flowchart TD
    subgraph Client ["SvelteKit Client"]
        A[Product Page] --> B[Checkout Component]
        B --> C[Dodo Overlay Checkout]
    end
    subgraph Server ["SvelteKit Server"]
        D[Form Action / API Route] --> E[Dodo SDK]
        F[Webhook Handler] --> G[Database Update]
        H[Load Function] --> I[Entitlement Check]
    end
    C -->|Payment Event| F
    E -->|Create Session| C
    G --> H
```

在这一架构中，SvelteKit 客户端负责用户界面和叠加式结账。服务端代码负责创建结账会话、接收 Webhook 等安全操作。Load 函数用于检查用户的订阅状态，并保护高级功能路由。这种关注点分离是 SvelteKit 的核心原则，能让你的应用更安全、更易维护。将 API 密钥保存在服务端，可以避免它们暴露给客户端，同时仍然提供流畅的用户体验。

Dodo Payments SDK 开箱即用地支持这一架构。SvelteKit 适配器提供了一组处理程序，你可以在服务端路由中使用它们来处理常见的支付任务。这意味着你无需编写大量样板代码来处理签名验证或载荷校验等工作。你可以专注于业务逻辑，把集成的技术细节交给适配器处理。这不仅能大幅节省时间，还能帮助你更快地将应用推向市场。

## 第 1 步：安装 SDK

第一步是在 SvelteKit 项目中安装必要的软件包。你需要 Dodo Payments SvelteKit 适配器和结账 SDK。

```bash
npm install @dodopayments/sveltekit dodopayments-checkout
```

`@dodopayments/sveltekit` 软件包为结账、客户门户和 Webhook 提供便捷的处理程序。`dodopayments-checkout` 软件包用于在客户端初始化并打开叠加式结账。

## 第 2 步：设置环境变量

接下来，需要配置环境变量。在项目根目录创建 `.env` 文件，并添加 Dodo Payments API 密钥和配置。

```env
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_secret_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_RETURN_URL=https://dodopayments.com/checkout/success
```

开发期间请务必使用测试密钥，准备上线时再切换为正式密钥。你可以在 Dodo Payments 控制台中找到这些密钥。

## 第 3 步：创建结账组件

现在来创建一个用于结账的 Svelte 组件。这个组件会初始化 Dodo Payments SDK，并提供一个用于打开叠加式结账的按钮。

```svelte
<script lang="ts">
  import { onMount } from 'svelte';
  import { DodoPayments } from 'dodopayments-checkout';

  export let checkoutUrl: string;
  let isLoading = false;

  onMount(() => {
    DodoPayments.Initialize({
      mode: 'test', // 生产环境请改为 'live'
      displayType: 'overlay',
      onEvent: (event) => {
        if (event.event_type === 'checkout.opened') {
          isLoading = false;
        } else if (event.event_type === 'checkout.error') {
          isLoading = false;
          console.error('Checkout error:', event.data?.message);
        }
      }
    });
  });

  async function handleCheckout() {
    isLoading = true;
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: checkoutUrl
      });
    } catch (error) {
      console.error('Failed to open checkout:', error);
      isLoading = false;
    }
  }
</script>

<button
  on:click={handleCheckout}
  disabled={isLoading}
  class="btn-primary"
>
  {isLoading ? 'Loading...' : 'Buy Now'}
</button>
```

这个组件使用 `onMount` 钩子，在组件加载时初始化一次 SDK。`handleCheckout` 函数使用作为 prop 传入的 `checkoutUrl` 打开叠加式结账。

## 第 4 步：创建用于 Webhook 的服务端端点

Webhook 对于让数据库与支付事件保持同步至关重要。每当支付成功、订阅续期或发生退款时，Dodo Payments 都会向你的 Webhook URL 发送 POST 请求。

创建文件 `src/routes/api/webhooks/+server.ts` 来处理这些事件。

```typescript
import { Webhooks } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_WEBHOOK_KEY } from "$env/static/private";
import { error } from "@sveltejs/kit";

export const POST = Webhooks({
  webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
  onSubscriptionActive: async (payload) => {
    const { customer, subscription_id } = payload.data;
    // 更新数据库，将用户标记为活跃
    console.log(`Subscription active for ${customer.email}`);
  },
  onPaymentSucceeded: async (payload) => {
    const { customer, total_amount } = payload.data;
    // 处理一次性支付成功事件
    console.log(`Payment of ${total_amount} succeeded for ${customer.email}`);
  },
  onSubscriptionCancelled: async (payload) => {
    const { customer } = payload.data;
    // 更新数据库，将用户标记为已取消
    console.log(`Subscription cancelled for ${customer.email}`);
  },
});
```

SvelteKit 适配器中的 `Webhooks` 处理程序会负责签名验证和载荷校验。你只需要为每种事件类型提供相应的逻辑。

## 第 5 步：使用表单操作创建结账会话

SvelteKit 表单操作非常适合处理结账会话的创建。你可以创建一个向服务端操作发送 POST 请求的表单，然后由该操作调用 Dodo Payments API 来获取结账 URL。

在 `+page.server.ts` 文件中：

```typescript
import { Checkout } from "@dodopayments/sveltekit";
import {
  DODO_PAYMENTS_API_KEY,
  DODO_PAYMENTS_RETURN_URL,
} from "$env/static/private";

const checkoutHandler = Checkout({
  bearerToken: DODO_PAYMENTS_API_KEY,
  returnUrl: DODO_PAYMENTS_RETURN_URL,
  type: "session",
});

export const actions = {
  default: checkoutHandler.POST,
};
```

在 `+page.svelte` 文件中：

```svelte
<script lang="ts">
  import { enhance } from '$app/forms';
  import CheckoutButton from './CheckoutButton.svelte';

  export let form;
</script>

<form method="POST" use:enhance>
  <input type="hidden" name="product_id" value="pdt_123" />
  <button type="submit" class="btn-primary">获取结账链接</button>
</form>

{#if form?.checkout_url}
  <CheckoutButton checkoutUrl={form.checkout_url} />
{/if}
```

这种模式支持渐进增强。如果 JavaScript 被禁用，表单仍然可以正常工作（但叠加式结账不会打开）。启用 JavaScript 后，`use:enhance` 指令会在不重新加载页面的情况下处理表单提交，而 `CheckoutButton` 会在 URL 返回后立即打开叠加式结账。这是 SvelteKit 的强大功能，能帮助你构建稳健、易访问的应用，无论用户的浏览器设置或网络状况如何，都可以正常使用。

使用表单操作也能更轻松地处理校验和错误状态。你可以使用 `@sveltejs/kit` 中的 `fail` 函数，将校验错误返回给客户端，然后在 Svelte 组件中显示。这能为用户提供流畅、集成式的体验，帮助他们顺利完成购买。你还可以使用 `form` store 访问操作返回的数据，从而轻松地将结账 URL 传递给结账组件。

## 第 6 步：在 Load 函数中检查权益

要保护高级内容，你需要在 Load 函数中检查用户的订阅状态。你可以将订阅状态存储在数据库中，并在用户访问受保护路由时查询该状态。

```typescript
import { redirect } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";

export const load: PageServerLoad = async ({ locals }) => {
  const session = await locals.getSession();
  if (!session) {
    throw redirect(303, "/login");
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
  });

  if (!user.isSubscribed) {
    throw redirect(303, "/pricing");
  }

  return {
    user: user,
  };
};
```

在 `load` 函数中检查状态，可以确保页面渲染前就在服务端完成检查。这样既能避免高级内容短暂"闪现"，也能提供安全的访问管理方式。

## SvelteKit 集成技巧

使用 Dodo Payments 部署 SvelteKit 应用时，有几个方面需要注意。

### 选择适配器

SvelteKit 支持 Vercel、Netlify 和 Cloudflare Pages 等多种适配器。Dodo Payments SvelteKit 适配器旨在兼容这些平台。不过，如果你使用的是无服务器环境，请确保 Webhook 处理程序运行迅速。如果数据库更新耗时过长，Webhook 可能会超时。通常来说，最好立即确认收到 Webhook，并在条件允许时通过后台任务处理更新。

### 在本地测试 Webhook

由于 Dodo Payments 需要一个公开 URL 来发送 POST 请求，在本地测试 Webhook 可能比较棘手。你可以使用 Ngrok 或 Localtunnel 等工具，将本地开发服务器创建为隧道。获得公开 URL 后，就可以在 Dodo Payments 控制台中将其配置为 Webhook 端点。

### SSR 与 CSR 结账

Dodo Payments 叠加式结账是一个客户端组件。它依赖服务端渲染（SSR）期间不可用的浏览器 API。因此，我们会在 Svelte 的 `onMount` 钩子中初始化 SDK，确保初始化操作只在浏览器中执行。

如果你需要在服务端生成结账 URL，请使用第 5 步介绍的服务端处理程序。这样可以保护 API 密钥，并让你在受控环境中处理相关逻辑。你还可以使用这种方式处理动态定价或自定义折扣，因为在创建结账会话前，你可以在服务端计算价格。这增加了一层安全防护，也能防止用户在浏览器中篡改价格。

### 处理重定向和成功页面

结账成功后，Dodo Payments 会使用你提供的 `returnUrl` 将用户重定向回你的应用。你应该创建一个成功页面，感谢用户购买，并提供订单所需的信息。你还可以在此页面触发客户端跟踪或分析事件。请务必在成功页面的 load 函数中检查用户的订阅状态，确保支付已正确处理，并且用户能够访问高级内容。

如果支付失败或用户取消结账，Dodo Payments 同样会将其重定向回你的应用。你应该通过显示有帮助的错误消息，并提供让用户重试的方式，来妥善处理这些情况。你可以使用查询参数将失败信息传递给应用，然后据此自定义错误消息。即使事情没有按计划进行，这也能减少流失，并为用户提供更好的体验。

## 内部链接和资源

如需进一步了解支付策略和架构，请查看我们的其他指南：

- [如何接受在线支付](https://dodopayments.com/blogs/how-to-accept-online-payments)
- [面向 SaaS 的嵌入式支付](https://dodopayments.com/blogs/embedded-payments-saas)
- [SaaS 支付架构](https://dodopayments.com/blogs/payments-architecture-saas)
- [面向 SaaS 的 MoR（名义商户）](https://dodopayments.com/blogs/merchant-of-record-for-saas)
- [如何在线销售软件](https://dodopayments.com/blogs/how-to-sell-software-online)
- [销售数字产品的最佳平台](https://dodopayments.com/blogs/best-platform-sell-digital-products)
- [订阅定价模式](https://dodopayments.com/blogs/subscription-pricing-models)
- [使用 Dodo Payments 进行 Vibe Coding](https://dodopayments.com/blogs/vibe-coding)

如需详细的技术文档，请参阅 Dodo Payments 官方文档：

- [叠加式结账文档](https://docs.dodopayments.com/developer-resources/overlay-checkout)
- [Webhook 集成指南](https://docs.dodopayments.com/developer-resources/webhooks)
- [Dodo Payments SDK](https://docs.dodopayments.com/developer-resources/dodo-payments-sdks)
- [通用集成指南](https://docs.dodopayments.com/developer-resources/integration-guide)

## 常见问题

### Dodo Payments 是否提供 SvelteKit SDK？

是的，Dodo Payments 通过 `@dodopayments/sveltekit` 软件包提供专用的 SvelteKit 适配器。该适配器包含用于结账会话、客户门户和 Webhook 的预构建处理程序，让你可以轻松利用 SvelteKit 的路由和服务端功能完成集成。

### 如何在 SvelteKit 中处理 Webhook？

你可以创建一个 API 路由（例如 `src/routes/api/webhooks/+server.ts`），并使用 Dodo Payments SvelteKit 适配器中的 `Webhooks` 处理程序来处理 Webhook。该处理程序会自动验证 Webhook 签名，并将事件路由到你的自定义逻辑。

### 可以使用 SvelteKit 表单操作处理支付吗？

当然可以。SvelteKit 表单操作是处理结账会话创建的推荐方式。你可以使用适配器中的 `Checkout` 处理程序，在服务端处理表单提交，并向客户端返回结账 URL。

### 结账组件支持 SvelteKit SSR 吗？

结账叠加层本身是客户端组件，必须在浏览器中初始化。不过，你仍然可以对页面的其余部分使用 SvelteKit 的服务端渲染。只需将 SDK 初始化逻辑放在 `onMount` 钩子中，确保它只在客户端运行即可。

### 如何部署使用 Dodo Payments 的 SvelteKit 应用？

你可以将 SvelteKit 应用部署到 SvelteKit 适配器支持的任何平台，例如 Vercel、Netlify 或 Cloudflare Pages。只需确保在部署平台的设置中配置环境变量（API 密钥和 Webhook 密钥）。

## 结语

将支付集成到 SvelteKit 应用中不必成为一件令人头疼的事。通过将 Dodo Payments 作为你的 MoR（名义商户），你可以跳过全球税务和合规的复杂工作，同时享受对开发者友好的集成体验。

借助 `@dodopayments/sveltekit` 适配器和叠加式结账 SDK，你可以在几分钟内构建专业、面向全球的支付流程。无论你是在构建简单的数字产品商店，还是复杂的订阅型 SaaS，SvelteKit 和 Dodo Payments 都能提供成功所需的工具。

准备好开始销售了吗？查看我们的[定价](https://dodopayments.com/pricing)，立即注册开发者账户。
---
- [More Payments articles](https://dodopayments.com/blogs/category/payments)
- [All articles](https://dodopayments.com/blogs)