---

name: sveltekit description: "使用 SvelteKit 构建全栈 Web 应用——文件路由、SSR、SSG、API 路由和表单操作集于一个框架。" category: frontend risk: safe source: community date_added: "2026-03-18" author: suhaibjanjua tags: [svelte, sveltekit, fullstack, ssr, ssg, typescript] tools: [claude, cursor, gemini]

SvelteKit 全栈开发

概述

SvelteKit 是构建在 Svelte 之上的官方全栈框架。它提供文件路由、服务端渲染（SSR）、静态站点生成（SSG）、API 路由和渐进式表单操作——所有这些都基于 Svelte 的编译时响应式模型，向浏览器发送零运行时开销。当构建 DX 和性能都重要的快速现代 Web 应用时使用此技能。

何时使用此技能

• 使用 Svelte 构建新的全栈 Web 应用时
• 需要按路由精细控制的 SSR 或 SSG 时
• 将 SPA 迁移到具有服务器能力的框架时
• 在需要文件路由和并置 API 端点的项目上工作时
• 当用户询问 +page.svelte、+layout.svelte、load 函数或表单操作时

工作原理

步骤 1：项目设置

npm create svelte@latest my-app
cd my-app
npm install
npm run dev

提示时选择 Skeleton project + TypeScript + ESLint/Prettier。

脚手架后的目录结构：

src/
  routes/
    +page.svelte        ← 根页面组件
    +layout.svelte      ← 根布局（包裹所有页面）
    +error.svelte       ← 错误边界
  lib/
    server/             ← 仅服务端代码（永不打包到客户端）
    components/         ← 共享组件
  app.html              ← HTML 外壳
static/                 ← 静态资源

步骤 2：文件路由

src/routes/ 中的每个 +page.svelte 文件直接映射到 URL：

src/routes/+page.svelte          → /
src/routes/about/+page.svelte    → /about
src/routes/blog/[slug]/+page.svelte  → /blog/:slug
src/routes/shop/[...path]/+page.svelte → /shop/*（通配）

路由组（无 URL 段）：包裹在 (group)/ 文件夹中。 私有路由（不可作为 URL 访问）：前缀 _ 或 (group)。

步骤 3：使用 load 函数加载数据

在页面旁使用 +page.ts（通用）或 +page.server.ts（仅服务端）文件：

// src/routes/blog/[slug]/+page.server.ts
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ params, fetch }) => {
  const post = await fetch(`/api/posts/${params.slug}`).then(r => r.json());

  if (!post) {
    error(404, 'Post not found');
  }

  return { post };
};

<!-- src/routes/blog/[slug]/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  export let data: PageData;
</script>

<h1>{data.post.title}</h1>
<article>{@html data.post.content}</article>

步骤 4：API 路由（服务端端点）

创建 +server.ts 文件用于 REST 风格端点：

// src/routes/api/posts/+server.ts
import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = async ({ url }) => {
  const limit = Number(url.searchParams.get('limit') ?? 10);
  const posts = await db.post.findMany({ take: limit });
  return json(posts);
};

export const POST: RequestHandler = async ({ request }) => {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return json(post, { status: 201 });
};

步骤 5：表单操作

表单操作是 SvelteKit 原生处理变更的方式——无需客户端 fetch：

// src/routes/contact/+page.server.ts
import { fail, redirect } from '@sveltejs/kit';
import type { Actions } from './$types';

export const actions: Actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    const email = data.get('email');

    if (!email) {
      return fail(400, { email, missing: true });
    }

    await sendEmail(email.toString());
    throw redirect(303, '/thank-you');
  }
};

步骤 6：布局和嵌套

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import Nav from '$lib/components/Nav.svelte';
</script>

<Nav />
<main>
  <slot />
</main>

步骤 7：部署适配器

# Node.js 服务器
npm install @sveltejs/adapter-node

# 静态站点
npm install @sveltejs/adapter-static

# Vercel
npm install @sveltejs/adapter-vercel

最佳实践

• 将敏感逻辑放在 +page.server.ts 中（永不暴露给客户端）
• 使用 $lib/server/ 存放仅服务端的工具函数
• 优先使用表单操作而非客户端 fetch 处理变更
• 使用 +layout.ts 中的 load 函数共享跨页面数据
• 利用 export const prerender = true 静态化不变页面

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来寻求澄清。