SvelteKit 最新中文文档教程（9）—— 部署静态站点与单页应用

前言

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

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

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

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

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

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

静态站点生成

要将 SvelteKit 用作静态站点生成器(SSG)，请使用 adapter-static。

这将把您的整个站点预渲染为静态文件集合。如果您想只预渲染某些页面而动态渲染其他页面，您需要使用不同的适配器，并结合prerender 选项。

使用方法

通过 npm i -D @sveltejs/adapter-static 安装，然后将适配器添加到您的 svelte.config.js 中：

// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
	kit: {
		adapter: adapter({
			// 显示默认选项。在某些平台上
			// 这些选项会自动设置 — 见下文
			pages: 'build',
			assets: 'build',
			fallback: undefined,
			precompress: false,
			strict: true
		})
	}
};

...并在根布局中添加 prerender 选项：

/// file: src/routes/+layout.js
// 如果您使用 fallback（即 SPA 模式），这可以设为 false
export const prerender = true;

[!NOTE] 您必须确保 SvelteKit 的 trailingSlash 选项适合您的环境。如果您的主机在收到 /a 的请求时不渲染 /a.html，那么您需要在根布局中设置 trailingSlash: 'always' 以创建 /a/index.html。

零配置支持

部分平台已支持零配置（未来将支持更多）：

• Vercel

在这些平台上，您应该省略适配器选项，以便 adapter-static 可以提供最佳配置：

// @errors: 2304
/// file: svelte.config.js
export default {
	kit: {
		adapter: adapter(---{...}---)
	}
};

选项

pages

预渲染页面的写入目录。默认为 build。

assets

写入静态资源（包括 static 的内容，以及 SvelteKit 生成的客户端 JS 和 CSS）的目录。通常这应该与 pages 相同，它会默认使用 pages 的值，但在极少数情况下，您可能需要将页面和资源输出到不同的位置。

fallback

为 SPA 模式 指定一个后备页面，例如 index.html 或 200.html 或 404.html。

precompress

如果为 true，则使用 brotli 和 gzip 预压缩文件。这将生成 .br 和 .gz 文件。

strict

默认情况下，adapter-static 会检查您的应用的所有页面和端点（如果有）是否都已预渲染，或者您是否设置了 fallback 选项。这个检查的存在是为了防止您意外发布一个部分内容无法访问的应用，因为这些内容不包含在最终输出中。如果您知道这是可以的（例如当某个页面只在特定条件下存在时），您可以将 strict 设置为 false 来关闭这个检查。

GitHub Pages

在为 GitHub Pages 构建时，如果您的仓库名称不等同于 your-username.github.io，请确保更新 config.kit.paths.base 以匹配您的仓库名称。这是因为站点将从 https://your-username.github.io/your-repo-name 而不是根目录提供服务。

您还需要生成一个后备 404.html 页面来替换 GitHub Pages 显示的默认 404 页面。

GitHub Pages 的配置可能如下所示：

// @errors: 2307 2322
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-static';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		adapter: adapter({
			fallback: '404.html'
		}),
		paths: {
			base: process.argv.includes('dev') ? '' : process.env.BASE_PATH
		}
	}
};

export default config;

您可以使用 GitHub actions 在进行更改时自动将您的站点部署到 GitHub Pages。以下是一个工作流示例：

### file: .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: 'main'

jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # 如果您使用 pnpm，添加此步骤然后更改下面的命令和缓存键以使用 `pnpm`
      # - name: Install pnpm
      #   uses: pnpm/action-setup@v3
      #   with:
      #     version: 8

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm install

      - name: build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: |
          npm run build

      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          # 这应该与适配器静态选项中的 `pages` 选项匹配
          path: 'build/'

  deploy:
    needs: build_site
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

如果您不使用 GitHub actions 部署您的站点（例如，您将构建的站点推送到它自己的仓库），请在您的 static 目录中添加一个空的 .nojekyll 文件，以防止 Jekyll 干扰。

单页应用

通过在根布局中禁用 SSR，您可以将使用任何适配器的任何 SvelteKit 应用转换为完全客户端渲染的单页应用（SPA）：

/// file: src/routes/+layout.js
export const ssr = false;

[!NOTE] 在大多数情况下不推荐这样做：它会损害 SEO，往往会降低感知性能，并且如果 JavaScript 失败或被禁用（这种情况发生的频率可能比您想象的要高），会使您的应用对用户不可访问。

如果您没有任何服务端逻辑（即没有 +page.server.js、+layout.server.js 或 +server.js 文件），您可以使用 adapter-static 通过添加一个后备页面来创建您的 SPA。

用法

使用 npm i -D @sveltejs/adapter-static 安装，然后在您的 svelte.config.js 中添加适配器，并使用以下选项：

// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
	kit: {
		adapter: adapter({
			fallback: '200.html' // 可能因主机而异
		})
	}
};

fallback 页面是 SvelteKit 根据您的页面模板（例如 app.html）创建的 HTML 页面，用于加载您的应用并导航到正确的路由。例如静态网站托管服务 Surge，允许您添加一个 200.html 文件，用于处理任何不对应于静态资源或预渲染页面的请求。

在某些主机上，它可能是 index.html 或完全不同的名称 — 请查阅您的平台文档。

[!NOTE] 请注意，无论 paths.relative 的值如何，后备页面将始终包含绝对资源路径（即以 / 而不是 . 开头），因为它用于响应任意路径的请求。

Apache

要在 Apache 上运行 SPA，您应该添加一个 static/.htaccess 文件，将请求路由到后备页面：

<IfModule mod_rewrite.c>
	RewriteEngine On
	RewriteBase /
	RewriteRule ^200\.html$ - [L]
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d
	RewriteRule . /200.html [L]
</IfModule>

预渲染单个页面

如果您想预渲染特定页面，您可以仅对应用的这些部分重新启用 ssr 和 prerender：

/// file: src/routes/my-prerendered-page/+page.js
export const prerender = true;
export const ssr = true;

Svelte 中文文档

点击查看中文文档：

• SvelteKit Node 服务端
• SvelteKit 单页应用

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

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

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