SvelteKit是什么？与Svelte区别、项目结构及SSR/SSG/SPA类型详解

本节目标：理解 SvelteKit 是什么、和 Svelte 的关系，了解不同项目类型和完整的项目目录结构。

SvelteKit 是什么

Svelte 是一个 UI 组件框架，负责渲染界面。但做一个完整的 Web 应用还需要路由、数据加载、服务端渲染、构建优化等能力。SvelteKit 就是补齐这些能力的外壳框架。

如果你用过 React 生态，SvelteKit 之于 Svelte 就像 Next 之于 React。如果你来自 Vue，那就像 Nuxt 之于 Vue。

SvelteKit 帮你处理的事情包括：

文件路由系统（点开一个 URL 就显示对应页面）
服务端渲染（SSR）和客户端水合
数据加载（load 函数）
表单处理（Form Actions）
构建优化和代码分割
页面预加载
环境变量管理

Tip

SvelteKit 基于 Vite 构建，开发时支持热更新（HMR），改代码后浏览器即时刷新，开发体验很快。

SvelteKit vs Svelte

对比项	Svelte	SvelteKit
定位	UI 组件框架	Web 应用框架
职责	渲染组件	路由、SSR、数据加载、构建
路由	无内置路由	文件路由系统
服务端	仅渲染组件为 HTML	完整的 SSR + API 端点
构建	需要手动配 Vite	开箱即用
适用	组件库、简单页面	完整 Web 应用

简单说：Svelte 是砖，SvelteKit 是用砖盖房子的施工框架。

项目类型

SvelteKit 支持多种渲染方式，你可以在同一个项目里混合使用：

SSR（服务端渲染）：默认方式。首屏在服务器渲染，后续导航在客户端渲染。SEO 友好，首屏快。

SSG（静态站点生成）：用 adapter-static 在构建时预渲染所有页面。适合博客、文档站。

SPA（单页应用）：纯客户端渲染。适合需要登录的管理后台，或后端用其他语言写的项目。

Note

这些渲染方式不互斥。你可以大部分页面用 SSR，少数页面用预渲染，某些页面禁用 SSR。灵活组合是 SvelteKit 的优势。

其他项目类型还包括：Serverless 部署、自有服务器部署、移动端应用（Tauri/Capacitor）、桌面应用（Electron）、浏览器扩展等。

创建项目

npx sv create

交互式选择模板、是否用 TypeScript、是否添加测试工具等。创建后的项目可以直接运行：

npm install
npm run dev

项目目录结构

一个典型的 SvelteKit 项目长这样：

my-project/
├── src/
│   ├── lib/
│   │   ├── server/
│   │   │   └── [服务端专用代码]
│   │   └── [组件和工具函数]
│   ├── params/
│   │   └── [路由参数匹配器]
│   ├── routes/
│   │   └── [路由文件]
│   ├── app.html
│   ├── app.d.ts
│   ├── hooks.client.js
│   └── hooks.server.js
├── static/
│   └── [静态资源]
├── package.json
├── svelte.config.js
├── tsconfig.json
└── vite.config.js

src 目录

src 是项目的核心目录：

lib/：放组件和工具函数，通过 $lib 别名导入
lib/server/：服务端专用代码，SvelteKit 防止它被打包到客户端
params/：路由参数匹配器
routes/：路由文件，这是最重要的目录
app.html：页面 HTML 模板
hooks.client.js / hooks.server.js：客户端和服务端的钩子函数

$lib 别名

src/lib 里的文件可以用 $lib 前缀导入，不用写相对路径：

// 不用这样
import Button from '../../lib/components/Button.svelte';

// 用 $lib 别名
import Button from '$lib/components/Button.svelte';

Tip

$lib/server 是服务端专用别名。SvelteKit 会阻止你在客户端代码中导入它，防止敏感代码泄漏到浏览器。

app.html

app.html 是页面 HTML 模板，所有页面都会用这个外壳：

<!doctype html>
<html lang="zh">
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
		%sveltekit.head%
	</head>
	<body data-sveltekit-preload-data="hover">
		<div style="display: contents">
			%sveltekit.body%
		</div>
	</body>
</html>

几个占位符的作用：

占位符	说明
`%sveltekit.head%`	页面需要的 `<link>`、`<script>` 和 `<svelte:head>` 内容
`%sveltekit.body%`	渲染出的页面标记
`%sveltekit.assets%`	静态资源路径
`%sveltekit.nonce%`	CSP nonce 值

Note

%sveltekit.body% 应该放在 <div> 内部，而不是直接在 <body> 上。浏览器扩展会往 <body> 注入元素，水合时会被清除，放在 div 里能避免冲突。

app.d.ts

TypeScript 项目中，app.d.ts 声明 SvelteKit 的类型：

import type { Adapter } from '@sveltejs/kit';

declare global {
	namespace App {
		interface Error {
			message: string;
			code?: string;
		}

		interface Locals {
			user?: {
				name: string;
				email: string;
			};
		}

		interface PageData {
			title?: string;
		}
	}
}

export {};

Locals 用于在服务端请求中存储用户信息等数据，Error 定义自定义错误类型，PageData 是所有 load 函数返回数据的类型基类。

svelte.config.js

SvelteKit 的配置文件：

import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess(),
	kit: {
		adapter: adapter(),
		alias: {
			$components: 'src/lib/components',
			$utils: 'src/lib/utils'
		}
	}
};

export default config;

关键配置项：

preprocess：预处理器，通常是 vitePreprocess()
kit.adapter：构建适配器，决定输出格式
kit.alias：自定义导入别名

Tip

适配器是 SvelteKit 的核心概念。adapter-auto 会根据部署平台自动选择。部署到 Vercel 就换 adapter-vercel，部署到 Node 服务器就换 adapter-node，纯静态站用 adapter-static。第 49 章会详细讲。

static 目录

static/ 放不需要处理的静态资源，如 favicon.ico、robots.txt。这些文件原样复制到输出目录。

Note

能用 import 引入的资源尽量用 import，而不是放 static/。Vite 会对导入的资源做哈希命名，缓存效果更好。

本节回顾

SvelteKit 是 Svelte 的应用框架，类似 Next 之于 React
支持多种渲染方式：SSR（默认）、SSG、SPA，可混合使用
src/routes/ 是路由目录，src/lib/ 是共享代码，用 $lib 别名导入
app.html 是页面模板，包含 %sveltekit.head% 和 %sveltekit.body% 等占位符
app.d.ts 声明 App.Locals、App.Error 等类型
svelte.config.js 配置预处理器、适配器和别名
static/ 放原样静态资源，其他资源用 import 引入

SvelteKit 简介与项目结构