SvelteKit 最新中文文档教程（16）—

SvelteKit 最新中文文档教程（16）—— Service workers

news2025/4/2 19:33:01

前言

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" /> 到引用类型中。