前言

Svelte，一个语法简洁、入门容易，面向未来的前端框架。

从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级、高性能、易上手等特性，非常适合构建轻量级 Web 项目。

为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。

如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。

仅服务端模块

SvelteKit 会像一个好朋友一样，保守您的秘密。在同一个代码仓库中编写后端和前端代码时，很容易不小心将敏感数据（例如包含 API 密钥的环境变量）导入到前端代码中。SvelteKit 提供了一种完全防止这种情况发生的方法：仅服务端模块（server-only modules）。

私有环境变量

$env/static/private 和 $env/dynamic/private 模块只能导入到仅在服务端上运行的模块中，例如 hooks.server.js 或 +page.server.js。

仅服务端工具

$app/server 模块包含一个 read 函数，用于从文件系统读取资源，同样只能被服务端运行的代码导入。

您的模块

您可以通过两种方式使您的模块成为仅服务端模块：

• 在文件名中添加 .server，例如 secrets.server.js
• 将它们放在 $lib/server 中，例如 $lib/server/secrets.js

工作原理

任何时候，当您有公开的代码，导入仅服务端代码时（无论是直接还是间接）...

// @errors: 7005
/// file: $lib/server/secrets.js
export const atlantisCoordinates = [
/* 已编辑 */
];

// @errors: 2307 7006 7005
/// file: src/routes/utils.js
export { atlantisCoordinates } from '$lib/server/secrets.js';

export const add = (a, b) => a + b;

/// file: src/routes/+page.svelte
<script>
import { add } from './utils.js';
</script>

...SvelteKit 将报错：

Cannot import $lib/server/secrets.js into public-facing code:
- src/routes/+page.svelte
  - src/routes/utils.js
    - $lib/server/secrets.js

尽管公开代码 — src/routes/+page.svelte — 只使用了 add 导出而没有使用秘密的 atlantisCoordinates 导出，秘密代码也可能最终出现在浏览器下载的 JavaScript 中，因此这个导入链被认为是不安全的。

此功能也适用于动态导入，甚至是像 await import(`./${foo}.js`) 这样的插值导入，只有一个小注意点：在开发过程中，如果公开代码和仅服务端模块之间存在两个或更多的动态导入，则在第一次加载代码时不会检测到非法导入。

[!NOTE] 像 Vitest 这样的单元测试框架不区分仅服务端代码和公开代码。因此，当运行测试时，非法导入检测会被禁用，这由 process.env.TEST === 'true' 决定。

进一步阅读

• 教程：环境变量

快照

临时的 DOM 状态 — 比如侧边栏的滚动位置、<input> 元素的内容等 — 在从一个页面导航到另一个页面时会被丢弃。

例如，如果用户填写了一个表单但在提交之前离开并返回，或者用户刷新页面，他们填写的值将会丢失。在需要保留这些输入的情况下，您可以创建一个 DOM 状态的快照，当用户返回时可以恢复这个状态。

要实现这一点，从 +page.svelte 或 +layout.svelte 中导出一个带有 capture 和 restore 方法的 snapshot 对象：

<!--- file: +page.svelte --->
<script>
  let comment = $state('');

  /** @type {import('./$types').Snapshot<string>} */
  export const snapshot = {
    capture: () => comment,
    restore: (value) => comment = value
  };
</script>

<form method="POST">
  <label for="comment">评论</label>
  <textarea id="comment" bind:value={comment} />
  <button>发表评论</button>
</form>

当您离开这个页面时，capture 函数会在页面更新之前立即被调用，返回的值会与浏览器历史栈中的当前记录关联。如果您返回此页面，restore 函数会在页面更新后立即被调用，并传入存储的值。

数据必须是可以序列化为 JSON 的，这样它才能被保存到 sessionStorage 中。这样就可以在页面重新加载时，或者用户从其他网站返回时恢复状态。

[!NOTE] 避免从 capture 返回非常大的对象 — 一旦被捕获，对象将在会话期间保留在内存中，在极端情况下可能会因太大而无法保存到 sessionStorage 中。

Svelte 中文文档

点击查看中文文档：

1. SvelteKit 仅服务端模块
2. SvelteKit 快照

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：github.com/mqyqingfeng…

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。

前言

Svelte，一个语法简洁、入门容易，面向未来的前端框架。

从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级、高性能、易上手等特性，非常适合构建轻量级 Web 项目。

为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。

如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。

Service workers

Service workers 作为代理服务端，处理应用程序内部的网络请求。这使得您的应用程序能够离线工作，但即使您不需要离线支持（或由于您正在构建的应用程序类型而无法实现它），使用 service workers 预缓存构建的 JS 和 CSS 来加快导航速度，通常也是值得的。

在 SvelteKit 中，如果您有一个 src/service-worker.js 文件（或 src/service-worker/index.js），它将被打包并自动注册。如果需要，您可以更改 service worker 的位置。

如果您需要使用自己的逻辑注册 service worker 或使用其他解决方案，可以禁用自动注册。默认注册看起来类似这样：

if ('serviceWorker' in navigator) {
addEventListener('load', function () {
navigator.serviceWorker.register('./path/to/service-worker.js');
});
}

Service Worker 内部

在 service worker 内部，您可以访问 $service-worker 模块，它为您提供所有静态资源、构建文件和预渲染页面的路径。您还会获得一个应用程序版本字符串，可用于创建唯一的缓存名称，以及部署的 base 路径。如果您的 Vite 配置指定了 define（用于全局变量替换），这也将应用于 service workers 以及服务端/客户端构建。

以下示例会尽可能早的缓存构建的应用程序和 static 中的所有文件，并在访问时缓存所有其他请求。这将使每个页面在访问后都能离线工作。

// @errors: 2339
/// <reference types="@sveltejs/kit" />
import { build, files, version } from '$service-worker';

// 为此部署创建唯一的缓存名称
const CACHE = `cache-${version}`;

const ASSETS = [
...build, // 应用程序本身
...files // `static` 中的所有内容
];

self.addEventListener('install', (event) => {
// 创建新缓存并添加所有文件
async function addFilesToCache() {
const cache = await caches.open(CACHE);
await cache.addAll(ASSETS);
}

event.waitUntil(addFilesToCache());
});

self.addEventListener('activate', (event) => {
// 从磁盘删除以前的缓存数据
async function deleteOldCaches() {
for (const key of await caches.keys()) {
if (key !== CACHE) await caches.delete(key);
}
}

event.waitUntil(deleteOldCaches());
});

self.addEventListener('fetch', (event) => {
// 忽略 POST 请求等
if (event.request.method !== 'GET') return;

async function respond() {
const url = new URL(event.request.url);
const cache = await caches.open(CACHE);

// `build`/`files` 始终可以从缓存中提供服务
if (ASSETS.includes(url.pathname)) {
const response = await cache.match(url.pathname);

if (response) {
return response;
}
}

// 对于其他所有内容，首先尝试网络
// 但如果我们离线，则回退到缓存
try {
const response = await fetch(event.request);

// 如果我们离线，fetch 可能返回非 Response 值
// 而不是抛出错误 - 我们不能将这个非 Response 传递给 respondWith
if (!(response instanceof Response)) {
throw new Error('invalid response from fetch');
}

if (response.status === 200) {
cache.put(event.request, response.clone());
}

return response;
} catch (err) {
const response = await cache.match(event.request);

if (response) {
return response;
}

// 如果没有缓存，就直接报错
// 因为我们无法对这个请求做任何响应
throw err;
}
}

event.respondWith(respond());
});

[!NOTE] 缓存时要小心！在某些情况下，过时的数据可能比离线时无法获取的数据更糟糕。由于浏览器会在缓存太满时清空缓存，因此您还应该谨慎缓存大型资源，如视频文件。

在开发过程中

service worker 在生产环境中会被打包，但在开发过程中不会。因此，只有支持 service workers 中的模块 的浏览器才能在开发时使用它们。如果您手动注册 service worker，在开发时需要传递 { type: 'module' } 选项：

import { dev } from '$app/environment';

navigator.serviceWorker.register('/service-worker.js', {
type: dev ? 'module' : 'classic'
});

[!NOTE] 在开发环境中，build 和 prerendered 是空数组

类型安全

为 service workers 设置适当的类型需要一些手动设置。在您的 service-worker.js 中，在文件顶部添加以下内容：

/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />

const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self));

/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />

const sw = self as unknown as ServiceWorkerGlobalScope;

这会禁用对 service worker 中不可用的 DOM 类型（如 HTMLElement）的访问，并实例化正确的全局变量。将 self 重新赋值给 sw 允许您在此过程中进行类型转换（有几种方法可以做到这一点，但这是最简单的，不需要额外的文件）。在文件的其余部分使用 sw 而不是 self。

对 SvelteKit 类型的引用确保 $service-worker 导入具有适当的类型定义。如果您导入 $env/static/public，您要么必须使用 // @ts-ignore 注释导入，要么添加 /// <reference types="../.svelte-kit/ambient.d.ts" /> 到引用类型中。

其他解决方案

SvelteKit 的 service worker 实现故意保持低级别。如果您需要更全功能但也更有主见的解决方案，我们建议查看像 Vite PWA 插件 这样的解决方案，它使用 Workbox。有关 service workers 的更多一般信息，我们推荐 MDN web 文档。

Svelte 中文文档

点击查看中文文档：SvelteKit Service workers

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：github.com/mqyqingfeng…

欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。