SvelteKit 实战：用文件路由与 SSR 构建全栈 Web 应用

SvelteKit 是基于 Svelte 的全栈 Web 框架，它用”文件路由”和”服务端渲染（SSR）”让你用同一套代码同时完成前端界面与后端接口。相比传统前后端分离的架构，SvelteKit 在开发体验、首屏性能和 SEO 上都更顺手。本文从项目初始化讲到生产部署，带你把 SvelteKit 的核心机制一次吃透。

一、为什么选 SvelteKit

Svelte 本身是一个”编译时”框架——它把组件编译成极小的原生 JS，运行时几乎没有框架开销，这让页面既轻又快。SvelteKit 在 Svelte 之上补齐了工程化能力：路由、数据加载、服务端接口、渲染策略、适配器部署，全部开箱即用。你不再需要自己拼接 Vite、React Router、Express 那一套，一个命令就能跑起一个既能渲染页面又能提供 API 的全栈应用。

它的设计哲学是”约定优于配置”：目录结构即路由，文件命名即行为。这种风格和 Hono 这类统一 API 框架的极简思路异曲同工，但 SvelteKit 更偏向带界面的 Web 应用，而不是纯 API 服务。和 Next.js、Nuxt 相比，SvelteKit 没有虚拟 DOM，组件在编译期就被优化成精细的更新指令，运行时更省内存；和纯前端方案相比，它又省去了自己再起一个后端服务的麻烦。对于一个中小团队或个人开发者，这种”少依赖、少概念”的取舍往往比性能数字更值钱。

二、快速初始化项目

2024 年起官方推荐使用 sv 脚手架。它会引导你选择模板（库模式、简约应用、博客/文档站点）和是否开启 TypeScript、Prettier、Playwright 测试。

# 使用官方 sv 脚手架（pnpm 示例）
npx sv create my-app
cd my-app
pnpm install
pnpm dev --open

脚手架会生成 src/routes、src/lib、static 等目录，以及一个 svelte.config.js。其中 kit.adapter 决定最终产物跑在哪里——这一点在第七节细说。

三、文件路由：目录即路由

SvelteKit 的路由完全由 src/routes 下的文件名约定决定：+page.svelte 是一个页面，+layout.svelte 是包裹子路由的布局，方括号文件夹 [slug] 是动态参数，+server.ts 则是纯接口。除了页面和接口，你还常见 +error.svelte（捕获该层级的渲染异常）和 +layout.ts（布局级的数据加载）。由于一切都落在文件系统里，新增一个页面就是新建一个文件，重构路由就是移动目录，IDE 里的结构树就是整张站点地图，新人上手几乎零认知成本。

src/routes/
├─ +layout.svelte      # 全局布局（导航/页脚）
├─ +page.svelte        # 首页 /
├─ about/
│  └─ +page.svelte     # /about
├─ blog/
│  ├─ +page.svelte     # 文章列表
│  └─ [slug]/
│     ├─ +page.ts      # 数据加载 load()
│     └─ +page.svelte  # 详情页
└─ api/
   └─ hello/
      └─ +server.ts    # GET/POST 接口

动态路由与数据加载

页面数据用同级的 +page.ts（或 .js）里的 load 函数加载，它既能在服务端跑，也能在客户端导航时跑。用框架内置的 fetch 可以在服务端直接请求接口而无需担心 cookie 与相对路径。

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

export const load: PageLoad = async ({ params, fetch }) => {
  const res = await fetch(`/api/posts/${params.slug}`);
  if (!res.ok) throw error(404, '文章不存在');
  const post = await res.json();
  return { post };
};

四、SSR 与 CSR：渲染模式怎么选

SvelteKit 允许你在每个页面甚至全局布局上精确控制渲染策略：ssr（服务端渲染）、csr（客户端 hydrate）、prerender（构建期预渲染为静态 HTML）。三者可以任意组合，比如一个营销页可以 prerender = true 直接产出静态文件，而一个强交互后台则保留 SSR + CSR。

// 单页控制渲染策略
export const ssr = true;       // 服务端渲染
export const csr = true;       // 客户端 hydrate
export const prerender = true; // 构建期预渲染为静态 HTML

// 也可在根布局统一设置
export const prerender = true;

三种模式的取舍如下：

五、服务端接口：+server 与 Form Actions

SvelteKit 把”后端”也纳入路由体系。任意目录下放一个 +server.ts，就能对外暴露标准的 HTTP 接口；如果在页面同级放 +page.server.ts，则可以定义表单 Action，天然处理 POST 提交，避免手写 fetch。

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

export const GET: RequestHandler = () => {
  return json({ message: 'Hello from SvelteKit' });
};

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

// src/routes/contact/+page.server.ts
import { fail } 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 });
    // 这里写入数据库或调用邮件服务
    return { success: true };
  }
};

如果你已经在用 tRPC 做类型安全 API，也可以把 SvelteKit 的 +server.ts 作为 tRPC handler 的入口，两者并不冲突。

六、与前端生态的衔接

SvelteKit 自带 Vite，支持任意 npm 包。需要类型安全的状态时可用 Vue3 + Pinia 同款思路把全局状态抽到 src/lib/stores；写代码时在 VS Code 里装好 Svelte 官方插件即可获得语法高亮与跳转。它和 Astro 也能配合——Astro 可以把 SvelteKit 当作一个 islands 渲染器。

七、部署：从 Node 到边缘

SvelteKit 通过”适配器（adapter）”把同一份源码编译成不同平台的运行形态。换平台基本只改 svelte.config.js 一行，无需动业务代码。

// svelte.config.js
import adapter from '@sveltejs/adapter-node';
// 也可换成 adapter-vercel / adapter-static / adapter-cloudflare
export default {
  kit: { adapter: adapter() }
};

# adapter-node 构建并启动（默认监听 3000）
pnpm build
node build/index.js

适配器选型参考：

用 Docker 自托管时，把 build 目录和 node 运行命令打进镜像即可；配合 GitHub Actions 还能在每次 push 后自动构建并推送镜像，实现持续交付。

八、生产落地检查清单

九、常见误区与排障

新手最容易踩的坑有三个：一是把只在服务端可用的密钥写进了客户端代码，导致泄漏；二是混淆 load 里的 fetch 与普通 fetch，在服务端忘记用框架注入的版本会让相对路径请求失败；三是预渲染时页面里存在动态参数却没设 entries，构建会报”无法预渲染”。排障时先看终端报错的文件路径，再对照上面的清单逐项核对，基本都能定位。

// 错误：客户端拿到了服务端密钥
export const prerender = true;
const key = import.meta.env.SECRET_KEY; // 会打包进前端包！

// 正确：服务端专用变量只在 +page.server.ts / +server.ts 使用
import { env } from '$env/dynamic/private';
const key = env.SECRET_KEY;

整体而言，SvelteKit 把”写一个既能看又能调接口的网站”这件事变得异常简洁。等你熟悉了文件路由与渲染策略，再叠加适配器与 CI，一个可上线、可维护的全栈应用就成型了。需要提醒的是，渲染策略不是越复杂越好：能静态预渲染的页面就别上 SSR，能用 SSR 的就别把逻辑全推给客户端，分层清晰才能既快又稳。先用最简单的默认配置跑通业务，再根据流量和收录需求逐步微调，是最稳妥的演进路径。