企业官网建设流程全解析

1. 从“数据从哪来”说起：加载函数到底解决了什么问题

先说一个很多人初学 SvelteKit 时的困惑：明明组件里可以写onMount、可以写fetch，为什么还要搞一个load函数？有这种疑问很正常，毕竟 Vue 的asyncData、Nuxt 的serverPrefetch、Next.js 的getServerSideProps，每个框架都有自己的数据获取方案，看起来都像“在渲染前拿数据”，但 SvelteKit 的load函数有几个非常关键的区别。

1.1 load 函数的核心职责

一句话总结：load函数是 SvelteKit 中页面与布局组件在渲染之前的数据准备入口。它把“数据获取”和“组件渲染”彻底分离，组件只负责接收数据，不负责“发起请求然后等待结果”这件事。

// 一个最基础的 +page.server.ts import type { PageServerLoad } from './$types'; export const load: PageServerLoad = async ({ params }) => { const response = await fetch(`https://api.example.com/posts/${params.slug}`); const post = await response.json(); return { post }; };

对应页面组件里：

<script lang="ts"> import type { PageData } from './$types'; export let data: PageData; </script> <h1>{data.post.title}</h1>

这个模式几乎所有人第一次看都觉得平平无奇，但真正用起来就会发现，它把原本散落在组件里的请求逻辑、loading 状态、错误处理全部收拢到了同一个地方。你可能不需要在组件里写if (loading)，因为路由跳转时 SvelteKit 会等待 load 完成再渲染；你也不需要手动处理取消请求，因为 load 函数的取消由框架统一管理。

1.2 区分两种 load：Universal Load 与 Server Load

这是 SvelteKit 里一个特别容易混淆的点。+page.ts里定义的load是Universal Load，它既可以在服务端运行，也可以在客户端运行；+page.server.ts里定义的load是Server Load，它只会在服务端运行。

后台管理后台之类的应用，服务端渲染时用 Server Load 拿数据；做个人博客时，如果数据源就是静态文件或者第三方 API，Universal Load 反而更灵活。

选择逻辑其实很简单：

• 需要访问数据库、私密环境变量、直接操作请求头 Cookie，就用.server.ts
• 数据可以在服务端拿，也可以在客户端拿，甚至完全依赖浏览器端 API，就用普通.ts
• 同一个路由两种都有时，Server Load 的返回值会自动成为 Universal Load 的parent数据，两者可以分层协作

2. 加载函数的运行机制：你在调用它之前必须先理解它的生命周期

load函数看名字像普通函数，但在 SvelteKit 里，它的执行时机、执行环境、缓存策略都是有完整规则的。我踩过最大的坑就是：以为它只是在页面加载时跑一次，结果发现导航时它也跑、invalidate时它也跑、甚至服务端和客户端各跑一次，数据对不上才意识到问题。

2.1 首次访问与客户端导航的区别

首次访问一个 URL，SvelteKit 会先跑服务端的load。注意这里指的是首屏 HTML 请求，不是只有+page.server.ts才会跑在服务端。如果你用的是 Universal Load（.ts文件），首次请求时它同样会在服务端执行，因为需要把数据塞进 HTML 里完成 SSR。

后续的客户端导航（点击<a>跳转、调用goto）则不同：+page.server.ts的 load 仍然会在服务端执行，返回的数据通过序列化传递到客户端；+page.ts的 load 则直接跑在浏览器里。这种差异隐含着性能问题的隐患：如果服务端 load 太重，每个导航都要等服务端返回，体验就会退化成一个“假 MPA”。

2.2 load 函数不能访问什么

这是很多新手容易踩的坑。Server Load 里默认接收的参数里没有event.request的完整 body 解析、没有event.clientAddress（需要配置适配器）、也不能直接 import 客户端专用模块。而 Universal Load 里没有event.cookies、event.locals里的某些字段可能也不存在。

安全边界也很重要：Universal Load 里写fetch请求时，如果访问的是同源 API，这个请求会直接走浏览器的 fetch，意味着它没有权限读取服务端密钥，也没有办法用event.fetch的 cookie 传递逻辑。

3. 实操：手把手写一个带分类筛选的列表页 load

讲原理讲多了容易飘，下面用一个真实场景完整串一遍。假设我要做一个博客的“文章列表页”，支持：

• 按分类筛选（?category=tech）
• 按页码分页（?page=2）
• 从 Cookie 里读取用户偏好的每页条数
• 服务端渲染首屏时直接带出数据

3.1 页面与服务端 Load 的代码结构

先定义+page.server.ts：

import type { PageServerLoad } from './$types'; interface ApiResponse { items: Array<{ id: string; title: string; category: string; publishedAt: string; }>; total: number; } export const load: PageServerLoad = async ({ url, cookies, fetch }) => { const category = url.searchParams.get('category') ?? 'all'; const page = Number(url.searchParams.get('page') ?? '1'); const pageSize = Number(cookies.get('page_size') ?? '10'); const apiUrl = new URL('https://api.example.com/posts'); apiUrl.searchParams.set('category', category); apiUrl.searchParams.set('page', String(page)); apiUrl.searchParams.set('pageSize', String(pageSize)); const response = await fetch(apiUrl); if (!response.ok) { throw new Error(`API responded with ${response.status}`); } const data: ApiResponse = await response.json(); return { posts: data.items, total: data.total, page, pageSize, category }; };

对应+page.svelte：

<script lang="ts"> import type { PageData } from './$types'; export let data: PageData; </script> <div class="toolbar"> <a href="?category=tech">技术</a> <a href="?category=life">生活</a> <a href="?category=all">全部</a> </div> <ul> {#each data.posts as post} <li><a href={`/posts/${post.id}`}>{post.title}</a></li> {/each} </ul> <p>第 {data.page} 页，共 {Math.ceil(data.total / data.pageSize)} 页</p>

注意这里筛选和分页用的是<a>链接，不是按钮点击后 JS 请求，这直接利用了 SvelteKit 的客户端导航机制，URL 变了，load 自动重跑，页面自动更新。

3.2 为什么推荐用 URLSearchParams 作为“加载函数状态”

筛选条件放在 URL 上，而不是放在组件内部变量里，原因有三：

1. 可共享：任何用户把当前 URL 复制给别人，看到的是同样的筛选结果
2. 可刷新：刷新页面不会丢失状态
3. 天然驱动 load：SvelteKit 在 URL 变化时会自动调用 load，你不必自己监听事件

这里我有个习惯：把load里的“输入参数”尽量限制在 URL 和 cookies 两类，不要直接读全局变量。全局变量一变，load 不会自动知道，你还得自己调invalidate()，非常容易漏。

4. 深挖细节：URL 依赖追踪与 invalidate 的使用时机

SvelteKit 的 load 函数强大在“依赖追踪”，但也容易在这里产生困惑。你需要理解什么时候 load 会被自动重跑，什么时候必须手动触发。

4.1 自动追踪与手动失效

SvelteKit 会自动追踪 load 里读取的 URL 值。比如url.searchParams.get('page')被读取后，只要 URL 中page变了，load 就会自动重跑。这是框架实现的“响应式依赖”。

但有些数据变化不会被自动追踪，典型的就是“用户点击刷新按钮后重新请求同一 URL”这种场景其实会自动跑，因为导航发生了。

而像“用户切换了主题，列表需要重新排序”、“用户点了刷新按钮，但数据源其实变了”这类场景，就需要手动触发。手动触发的 API 是：

import { invalidate } from '$app/navigation'; // 让某个 URL 关联的数据失效 await invalidate('https://api.example.com/posts');

import { invalidateAll } from '$app/navigation'; // 让当前页面所有 load 全部重跑 await invalidateAll();

这是很多 SvelteKit 初学者的盲区：以为 load 是“进来跑一次就完事”，结果做了个“换主题重新排序”的功能，发现点了按钮页面纹丝不动。

4.2 使用depends声明自定义依赖

手动失效有个更优雅的方式，就是depends。你可以在 load 里声明一个自定义依赖标识，然后在交互逻辑里失效它。

export const load: PageServerLoad = async ({ depends, fetch }) => { // 声明依赖 depends('blog:posts'); const res = await fetch('https://api.example.com/posts'); return { posts: await res.json() }; };

import { invalidate } from '$app/navigation'; // 任意组件里触发 await invalidate('blog:posts');

最直观的场景：用户在某处“发表了一篇新文章”，你希望文章列表刷新但不想刷新整页。这比自己封装事件广播要干净得多。

5. 进阶玩法：服务端 Load 的流式数据与渐进式渲染

如果你的数据里有“必须拿回来才能渲染”的关键字段，但也有“可以稍后填充”的次要数据，可以使用 SvelteKit 2.x 的流式加载。

5.1 同时返回普通数据和 Promise

在+page.server.ts里：

export const load: PageServerLoad = async ({ fetch }) => { // 立即返回核心数据 const base = await fetch('https://api.example.com/base').then(r => r.json()); // 次要数据用 Promise 返回，SvelteKit 会把它作为流式数据 const secondary = fetch('https://api.example.com/secondary').then(r => r.json()); return { base, secondary }; };

组件里用{#await}处理流式部分：

<p>核心数据：{data.base.title}</p> {#await data.secondary} <p>次要数据加载中...</p> {:then items} <ul> {#each items as item} <li>{item.name}</li> {/each} </ul> {:catch error} <p>次要数据加载失败</p> {/await}

这种模式非常适合详情页：先渲染标题、简介、主图，评论区、相关推荐等可以做流式加载。首屏时间能显著下降。

5.2 流式加载的序列化限制

流式数据不是万能的，它有一个硬性限制：流式加载的数据在服务端无法作为parent数据来源，因为parent的同步读取要求数据已经完整。另一个限制是：+page.ts（Universal Load）里不能直接返回 Promise，因为它需要在客户端也能同步读取。如果你一定要用流式，必须有.server.ts版本。

6. 真实场景中的“为什么”解析：几个高频问题与排查手册

把实际项目中频繁踩到的问题整理成速查表，每一个都是我亲身经历过或者帮别人排查过的问题。

6.1 服务端 load 里的 fetch 为什么拿不到 Cookie

这是最常见的问题。你在+page.server.ts的load里写：

const res = await fetch('https://api.example.com/me'); // 没带 cookie

这个 fetch 走的是 Node/服务端环境，不是浏览器。除非你显式传 headers，否则不会自动带上浏览器 Cookie。正确做法是用 SvelteKit 提供的event.fetch，它会继承请求的 Cookie 头：

export const load: PageServerLoad = async ({ fetch }) => { const res = await fetch('https://api.example.com/me'); // 自动带 cookie return { me: await res.json() }; };

提示：event.fetch在 Server Load 里已经是“继承请求上下文”的版本；在 Universal Load 里，它等价于浏览器的原生 fetch。这俩别搞混。

6.2 fetch 自身路由导致的“死循环”

如果服务端 load 里 fetch 的是应用自己的路由（比如/api/posts.json），而这个路由本身又触发load，就会形成死循环，页面卡住直到超时。

解决办法：

• 优先用直接读取数据源的方式，而不是 fetch 自身路由
• 如果确实要复用路由逻辑，把核心逻辑拆成独立函数，load 和 route handler 都调用它
• 或者给 fetch 加上internal: fetch的 SvelteKit 特有头，让它绕过自身应用的 load 触发

这个问题的排查非常痛苦，因为输出日志里没有明显报错，只有“服务端响应超时”，我是靠逐个去掉 fetch 才发现问题的。

6.3 巨大列表页的性能问题：load 频繁重跑

如果你在 load 里读取了url.searchParams.get('keyword')，然后在组件里用{#each}渲染几千条数据，每次敲一个字都会触发 load 重跑。要看数据量：如果是几千条本地数组，其实没多大事，但如果是几万条需要重新序列化，页面就会卡。

优化方向：

1. 加防抖：不在 load 里处理搜索，而是先在组件里本地筛选，URL 只存“最终确认的筛选后状态”
2. 用流式加载拆成两步：先渲染列表框架，keywords 变化后再拿完整列表
3. 如果数据源在数据库，给查询加缓存，避免每次 load 都打一次数据库

6.4data为 undefined 或空值的情况

SvelteKit 的类型系统里，PageData的某些字段可能是可选的。如果你在 load 里没有返回某个键，组件里读的时候会得到undefined。这种问题在 TS 严格模式下会直接报错，但 JS 项目里很容易漏。

我的习惯：load 返回的数据结构尽量“扁平化 + 必有字段非空”，不需要的值就明确返回null，不要不返回。这能减少大量边界判断。

6.5 自定义 adapter 环境里 load 执行环境的差异

如果你的项目部署在 Node 环境，Server Load 拿到的是标准 Request 对象；如果部署在 Edge 环境（比如 Cloudflare Workers、Deno Deploy），event.platform会有额外的上下文（比如 Workers 的 env 绑定）。这会影响你的代码写法：比如访问数据库的库，在 Node 和 Edge 下的调用方式不同。

建议：不要在你的 load 里直接写死环境相关的 API，做一个platform.ts做环境适配层，load 只调用抽象接口。

7. 从源码层面理解加载函数的依赖收集机制

这里讲点稍微硬核的内容。SvelteKit 内部会用一个依赖图来记录 load 和它消费的数据源。当你调用invalidate(url)或invalidateAll()时，框架会检查哪些 load 注册了依赖，然后只重跑相关的。

这个“依赖图”的关键点在于：它跟踪的不是组件，而是 URL 字符串和自定义依赖 ID。所以你在 load 里读取了fetch(someUrl)之后，这个someUrl就成了该 load 的依赖项。之后只要invalidate(someUrl)触发，这个 load 就会被重跑。

这段机制解释了为什么最好把 API 的 URL 作为常量提取出来，而不是写在 load 内部。比如：

// 不推荐 const res = await fetch(`https://api.example.com/posts?page=${page}`); // 推荐 const LIST_API = 'https://api.example.com/posts'; ... const res = await fetch(`${LIST_API}?page=${page}`);

这样将来写invalidate(LIST_API)时，能精确命中所有依赖这个地址的 load。

如果你看到+page.ts（Universal Load）和+page.server.ts同时出现，有个额外规则：+page.ts的 load 会把+page.server.ts返回的数据作为parent。这意味着你可以做分层数据组装：server load 负责拿原始数据，client load 负责加工（比如根据浏览器时区格式化时间）。注意parent的数据流在 universal 端只包含 server load 的返回值，不包含这个 universal load 自己之前返回的数据，因为一个 load 不能直接读自己的输出。

8. 代码组织与几个独家实操心得

8.1 load 里到底该写哪些逻辑

很多人一开始会把所有逻辑都塞进 load：数据校验、权限判断、日志埋点、甚至页面标题生成。我建议的边界是：

• 职责一：确定当前请求所需的数据（查询参数、Cookie、URL 里的 id）
• 职责二：获取并组装数据
• 职责三：设置必要的事件响应（如 redirect、error、cookies 操作）

至于“这个数据要展示成什么颜色”“列表要不要排序”，这些应该放在组件里。load 的返回值保持“原始数据形态”，不要在 load 里做 CSS 类的判断，否则你会在数据层引入展示层逻辑，后续维护会出现“改了样式还要改数据层”的怪现象。

8.2 组合式 load：把通用逻辑抽成函数

当多个页面有相同的 load 逻辑（比如都需要读取当前用户），直接写一个共享函数：

// lib/auth.ts import { redirect, type RequestEvent } from '@sveltejs/kit'; export async function requireUser(event: RequestEvent) { const session = await getSession(event.cookies); if (!session) { throw redirect(303, '/login'); } return session.user; }

然后每个 server load 里调用：

import { requireUser } from '$lib/auth'; export const load: PageServerLoad = async (event) => { const user = await requireUser(event); return { user }; };

8.3 过度使用加载函数的反面案例

我见过最离谱的项目把所有静态配置全部交给了 load，页面加载时每个路由都要去数据库读一遍。实际上 SvelteKit 完全支持+page.svelte里直接 import 静态 JSON 文件，根本不需要走 load。load 是解决“需要服务端逻辑或请求”的场景，不是唯一的数据入口。

8.4 加载函数与 SSR 的配合：写一个可测试的 load

最后分享一个提高代码可测试性的技巧。load 是一个纯函数，event参数可以轻易 mock。你可以直接写单元测试：

import { load } from './+page.server'; import { describe, it, expect, vi } from 'vitest'; describe('load', () => { it('returns posts with current page', async () => { const event = { url: new URL('https://demo.test/posts?page=2'), cookies: { get: () => '10' }, fetch: vi.fn().mockResolvedValue({ ok: true, json: async () => ({ items: [{ id: '1', title: 'A' }], total: 20 }) }) }; const result = await load(event as any); expect(result.page).toBe(2); expect(result.posts).toHaveLength(1); }); });

这比把数据获取混进组件里再测要容易非常多。说白了，load 函数设计成纯函数，本身就是为了可测试性和可组合性。

9. 结尾：

做了这么多年前端框架的数据层设计，SvelteKit 的 load 函数是我觉得最接近“直觉”的一个。它不要求你学习复杂的 action 语法或 state 管理概念，而是把“URL 即状态”这条原则贯彻到底。你要是刚开始接触，花一下午把+page.server.ts和+page.ts的区别跑通，再用invalidate做一个依赖刷新的小功能，基本就能掌握核心用法了。

个人实操中我最喜欢的一个小技巧是：所有需要登出的操作，直接invalidateAll()而不是手动清空一堆缓存。因为后端 session 一删，所有依赖用户数据的 load 都应该重跑，这时候手动指定某个依赖反而容易漏。

如果后续想深入，建议去读 SvelteKit 官方文档里event.fetch与fetch的区别、以及stream在真实项目里的性能数据。我不建议一上来直接啃源码，先把 load 的依赖收集、不同环境差异、流式加载这三个方向吃透，项目的性能优化和代码组织都会顺畅很多。