Sveltepress

介绍

此特性集成了 @vite-pwa/sveltekit

传递 pwa 选项给默认主题来使用 PWA，该选项与 SvelteKit PWA Plugin Options 完全一致，并新增了 darkManifest，可以用来配置夜间模式下的 manifest 文件

在 svelte.config.js 中使用从 @sveltepress/theme-default 导出的 SERVICE_WORKER_PATH 配置 files.serviceWorker

svelte.config.js
+
+
+
+
import function adapter(options?: AdapterOptions): Adapteradapter from '@sveltejs/adapter-static'
import { function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess } from '@sveltejs/vite-plugin-svelte'

import { const SERVICE_WORKER_PATH: stringSERVICE_WORKER_PATH } from '@sveltepress/theme-default' 

/** @type {import('@sveltejs/kit').Config} */
const 

const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
        files: {
            serviceWorker: string;
        };
    };
}
@type{import('@sveltejs/kit').Config}
config = {
  extensions: string[]extensions: ['.svelte', '.md'],
  preprocess: PreprocessorGroup[]preprocess: [function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroupvitePreprocess()],
  

kit: {
    adapter: Adapter;
    files: {
        serviceWorker: string;
    };
}
kit: {
    adapter: Adapteradapter: function adapter(options?: AdapterOptions): Adapteradapter(),
    

files: {
    serviceWorker: string;
}
files: { 
      serviceWorker: stringserviceWorker: const SERVICE_WORKER_PATH: stringSERVICE_WORKER_PATH, 
    }, 
  },
}

export default 

const config: {
    extensions: string[];
    preprocess: PreprocessorGroup[];
    kit: {
        adapter: Adapter;
        files: {
            serviceWorker: string;
        };
    };
}
@type{import('@sveltejs/kit').Config}
config
ts
依赖需要

需要安装 workbox-window 来使得 PWA 功能正确工作

npm install --save workbox-window
sh
yarn add workbox-window
sh
pnpm install workbox-window
sh
bun add workbox-window
sh

预缓存（多版本 / 多语言）

默认情况下，Sveltepress 只预缓存应用壳和首页 HTML。应用壳是 SvelteKit 的入口模块、哈希后的 CSS / 字体，以及站点根目录图标，不包含各路由的 _app/immutable/nodes 和共享 chunks。其它文档页和这些哈希模块会在用户访问时写入运行时缓存（页面：NetworkFirst，最多 50 条；哈希客户端文件：CacheFirst，最多 400 条 / 30 天）。图片和 SvelteKit 的 __data.json 也会进入运行时缓存。

这样在页面多、版本多、语言多时，Service Worker 的安装和更新仍然很快，站点更新后可以尽快弹出刷新提示。如果把所有预渲染 HTML 或全部客户端模块都放进 precache，每次更新 Workbox 都要哈希、对比、下载 版本 × 语言 × 页面 的笛卡尔积。

首次安装时，首页的 hydration 可能仍需要网络，直到这些哈希模块被写入运行时缓存。在线访问过一次之后，访问过的页面（包括首页）仍可通过运行时缓存离线打开。

pwa.precachePages

取值预缓存的 HTML
false（默认）仅首页
true全部预渲染 HTML（历史版本仍会被忽略）
string[]首页 + 匹配的 URL 前缀

只预缓存中文和某个版本快照：

import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'

function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
  

DefaultThemeOptions.pwa?: (SvelteKitPWAOptions & {
    darkManifest?: string;
    precachePages?: boolean | string[];
    precacheClient?: boolean;
}) | undefined
pwa: {
    precachePages?: boolean | string[] | undefined
Which prerendered HTML pages to put in the Workbox precache.


Default false only precaches the homepage so service-worker
install/update stays fast on sites with many versions and locales.


    

  • false: homepage only
    • 

  • true: all prerendered HTML (historical versions are still ignored)
    • 

  • string[]: URL prefixes, e.g. ['/zh/', '/v/2026-08-27/']
    • 

precachePages: ['/zh/', '/v/2026-08-27/'],
  },
})
ts

恢复「缓存全部页面」的旧行为：

import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'

function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
  

DefaultThemeOptions.pwa?: (SvelteKitPWAOptions & {
    darkManifest?: string;
    precachePages?: boolean | string[];
    precacheClient?: boolean;
}) | undefined
pwa: {
    precachePages?: boolean | string[] | undefined
Which prerendered HTML pages to put in the Workbox precache.


Default false only precaches the homepage so service-worker
install/update stays fast on sites with many versions and locales.


    

  • false: homepage only
    • 

  • true: all prerendered HTML (historical versions are still ignored)
    • 

  • string[]: URL prefixes, e.g. ['/zh/', '/v/2026-08-27/']
    • 

precachePages: true,
  },
})
ts
TIP

配置里必须保留一条以 prerendered/ 开头的 glob。否则 @vite-pwa/sveltekit 会自动补上 prerendered/**/*.{html,json}，所有版本和语言的页面又会回到 precache。

即使页面没有被预缓存，用户访问过的页面仍可通过运行时缓存离线打开。

应用壳客户端预缓存

pwa.precacheClient

取值预缓存的客户端文件
false（默认）仅应用壳（入口 + CSS / 字体 + 根目录图标）
true全部匹配的客户端文件

恢复「预缓存每一个客户端 JS/CSS 模块」的旧行为：

import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'

function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
  

DefaultThemeOptions.pwa?: (SvelteKitPWAOptions & {
    darkManifest?: string;
    precachePages?: boolean | string[];
    precacheClient?: boolean;
}) | undefined
pwa: {
    precacheClient?: boolean | undefined
Which client files to put in the Workbox precache.


Default false only precaches the app shell (SvelteKit entry,
hashed CSS/fonts, and root icons) so service-worker install/update
stays fast on sites with many pages. Per-route nodes and chunks
are fetched on demand.


    

  • false: app shell only
    • 

  • true: every matching client file (the previous catch-all glob)
    • 

precacheClient: true,
  },
})
ts

precachePages 和 precacheClient 彼此独立：HTML 策略不会改变客户端 glob，反之亦然。

配置示例

用此站点使用的配置来举例：

export default {
  scope: stringscope: '/',
  base: stringbase: '/',
  strategies: stringstrategies: 'generateSW',
  

kit: {
    trailingSlash: string;
}
kit: {
    trailingSlash: stringtrailingSlash: 'always',
  },
  darkManifest: stringdarkManifest: '/manifest-dark.webmanifest',
  

manifest: {
    start_url: string;
    scope: string;
    name: string;
    short_name: string;
    icons: {
        src: string;
        sizes: string;
        type: string;
    }[];
    theme_color: string;
    background_color: string;
    display: string;
}
manifest: {
    start_url: stringstart_url: '/',
    scope: stringscope: '/',
    name: stringname: 'Sveltepress',
    short_name: stringshort_name: 'Sveltepress',
    

icons: {
    src: string;
    sizes: string;
    type: string;
}[]
icons: [
      {
        src: stringsrc: '/android-chrome-192x192.png',
        sizes: stringsizes: '192x192',
        type: stringtype: 'image/png',
      },
      {
        src: stringsrc: '/android-chrome-512x512.png',
        sizes: stringsizes: '512x512',
        type: stringtype: 'image/png',
      },
    ],
    theme_color: stringtheme_color: '#f2f2f2',
    background_color: stringbackground_color: '#f2f2f2',
    display: stringdisplay: 'standalone',
  },
} as any
ts
Expand code