48. 页面选项与渲染模式

三个渲染选项

SvelteKit 默认用 SSR 渲染首屏，然后水合为 CSR 应用。你可以逐页控制这个行为：

选项	默认	作用
ssr	true	是否在服务端渲染
csr	true	是否在客户端水合（启用 JavaScript）
prerender	false	是否在构建时预渲染为静态 HTML

在 +page.js、+page.server.js、+layout.js 或 +layout.server.js 中导出：

// src/routes/+page.js
export const ssr = true;
export const csr = true;
export const prerender = false;

prerender：预渲染

预渲染在构建时生成静态 HTML 文件。适合内容不随用户变化页面：

// src/routes/about/+page.js
export const prerender = true;

预渲染的规则：

• 两个不同用户访问同一个预渲染页面，看到的内容必须相同
• 不能访问 url.searchParams（构建时没有查询参数）
• 有 Form Actions 的页面不能预渲染
• 预渲染器从根路由开始爬取 <a> 链接，自动发现页面

prerender 有三个值：

值	行为
true	必须预渲染，不被发现会报错
false	不预渲染
'auto'	尽量预渲染，没发现也不报错（可用于 /blog/[slug] 这种动态路由）

entries：预渲染动态路由

预渲染器通过爬取 <a> 链接发现页面。但动态路由的参数值它猜不到。用 entries 告诉它：

// src/routes/blog/[slug]/+page.server.js
/** @type {import('./$types').EntryGenerator} */
export function entries() {
	return [
		{ slug: 'hello-world' },
		{ slug: 'svelte-5-guide' }
	];
}

export const prerender = true;

entries 可以是异步函数，从 CMS 或数据库获取所有文章的 slug：

export async function entries() {
	const posts = await fetch('https://api.example.com/posts').then(r => r.json());
	return posts.map(p => ({ slug: p.slug }));
}

ssr：服务端渲染

关闭 SSR 后，页面只渲染一个空壳，内容在浏览器端由 JavaScript 渲染：

// src/routes/admin/+page.js
export const ssr = false;

适用场景：

• 页面大量使用浏览器 API（如 document、window）
• 管理后台等不需要 SEO 的页面

csr：客户端渲染

关闭 CSR 后，页面不加载 JavaScript，纯 HTML + CSS：

// src/routes/blog/[slug]/+page.js
export const csr = false;

关闭 CSR 的效果：

• 不发送任何 JavaScript 到浏览器
• 组件中的 <script> 被移除
• 表单无法用 use:enhance
• 链接导航变为整页刷新
• HMR 在开发时失效

import { dev } from '$app/environment';
export const csr = dev; // 开发时启用，生产时关闭

布局级配置

在 +layout.js 中导出的选项会作为所有子页面的默认值。子页面可以覆盖：

// src/routes/+layout.js
export const prerender = true;  // 全站默认预渲染

// src/routes/dashboard/+page.js
export const prerender = false; // 仪表板不预渲染
export const ssr = true;        // 但仍然 SSR

混合渲染模式

SvelteKit 的强大之处在于可以混合渲染模式：

src/routes/
├ +layout.js          → export const prerender = true
├ about/+page.js      → 预渲染（静态 HTML，无 JS）
├ blog/[slug]/        → SSR（动态内容，SEO 友好）
├ admin/+page.js      → ssr=false, csr=true（纯 SPA）
└ dashboard/          → SSR + CSR（默认模式）

trailingSlash

控制 URL 尾部斜杠的行为：

// src/routes/+layout.js
export const trailingSlash = 'always'; // 或 'never'（默认）或 'ignore'

值	行为
'never'	去掉尾部斜杠，/about/ 重定向到 /about
'always'	添加尾部斜杠，/about 重定向到 /about/
'ignore'	不处理（不推荐）

config 选项

config 选项用于给适配器传递配置。不同适配器有不同的配置项：

// src/routes/+page.js
/** @type {import('some-adapter').Config} */
export const config = {
	runtime: 'edge'  // 部署到边缘节点
};

子页面的 config 会和父布局的 config 在顶层合并。

本节回顾

• ssr 控制服务端渲染，csr 控制客户端水合，prerender 控制构建时预渲染
• 预渲染要求所有用户看到相同内容，不能访问 searchParams
• entries 函数告诉预渲染器动态路由有哪些参数值
• 关闭 SSR 变成 SPA，关闭 CSR 变成纯 HTML 页面
• 布局级选项作为子页面默认值，子页面可覆盖
• SvelteKit 支持混合渲染：同一应用中不同页面用不同渲染方式
• trailingSlash 控制 URL 尾部斜杠，影响预渲染文件结构