04. 部署与进阶 · FisherHub Docs

SvelteKit 的适配器系统让你可以将应用部署到各种平台。它同时支持多种渲染模式，从服务端渲染到纯静态导出。本章将系统介绍部署方案和进阶优化。

适配器 (Adapter)

适配器负责将 SvelteKit 应用转换为目标平台可运行的形式。SvelteKit 官方提供多种适配器。

adapter-cloudflare

部署到 Cloudflare Pages，适合边缘计算场景：

bun add --dev @sveltejs/adapter-cloudflare

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: {
    adapter: adapter({
      // 路由规则
      routes: {
        include: ['/*'],
        exclude: ['<all>']
      }
    })
  }
};

运行时环境： Cloudflare Pages 运行在 Workers 运行时（基于 Service Worker API），部分 Node.js API 不可用。如需使用 Node.js 特性，请选择 adapter-node。

adapter-static

将应用构建为纯静态文件，部署到任意静态托管服务（Nginx、S3、GitHub Pages 等）：

bun add --dev @sveltejs/adapter-static

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: 'index.html' // SPA 模式需要
    })
  }
};

adapter-node

部署到自托管 Node.js 服务器：

bun add --dev @sveltejs/adapter-node

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      out: 'build'
    })
  }
};

构建后运行：

bun run build
node build/index.js

SSR vs SSG vs SPA

SvelteKit 支持三种渲染模式，可以在同一个项目中混合使用。

SSR (服务端渲染)

默认模式。每次请求在服务端渲染 HTML 后发送到浏览器。

优点： SEO 友好，首屏加载快
适用： 内容网站、电商、需要 SEO 的应用

SSG (静态生成)

在构建时预渲染所有页面为静态 HTML。

// src/routes/+page.ts 或 +page.server.ts
export const prerender = true;

在 svelte.config.js 中全局配置：

export default {
  kit: {
    prerender: {
      crawl: true,
      entries: ['*'] // 自动发现所有路由
    }
  }
};

优点： 部署简单、加载极快、零服务端开销
适用： 博客、文档站、营销页面

SPA (单页应用)

在客户端渲染所有页面，服务端只提供空壳 HTML。

export const ssr = false;

同时需要 adapter-static 配合 fallback 配置：

优点： 完全静态部署、前端体验流畅
适用： 仪表盘、管理后台、工具型应用

混合模式

你可以在不同路由使用不同模式：

// src/routes/+layout.ts — 全局配置
export const ssr = true;

// src/routes/admin/+layout.ts — 管理后台关闭 SSR
export const ssr = false;
export const prerender = false;

// src/routes/about/+page.ts — 关于页面预渲染
export const prerender = true;

环境变量管理

SvelteKit 提供两套环境变量系统。

公共环境变量

以 PUBLIC_ 前缀开头的变量会暴露给前端。在代码中使用 $env/static/public 编译时注入，或 $env/dynamic/public 运行时读取：

PUBLIC_API_URL=https://api.fisherhub.cn

import { PUBLIC_API_URL } from '$env/static/public';
// 或运行时: import { env } from '$env/dynamic/public';

async function getPosts() {
  const res = await fetch(`${PUBLIC_API_URL}/posts`);
  return res.json();
}

私有环境变量

不暴露给前端的变量，只能在 +page.server.ts、+server.ts、hooks.server.ts 中使用：

DATABASE_URL=postgres://localhost:5432/mydb
API_SECRET_KEY=sk-xxxxx

// +page.server.ts
import { DATABASE_URL } from '$env/static/private';
// 或 import { env } from '$env/dynamic/private';

配置文件 (.env)

创建 .env 文件（注意加入 .gitignore）：

PUBLIC_API_URL=http://localhost:5173
DATABASE_URL=postgres://localhost:5432/dev

SvelteKit 会自动加载 .env、.env.local、.env.production 等文件。

性能优化

图片处理

使用 SvelteKit 内置的图片优化（需 adapter 支持）：

<script lang="ts">
  import { picture } from '$lib/images';
</script>

<picture>
  <source srcset={picture('/hero.jpg', { widths: [480, 768, 1200], formats: ['avif', 'webp'] })} />
  <img src="/hero.jpg" alt="Hero 图片" loading="lazy" />
</picture>

最佳实践：

使用 loading="lazy" 延迟加载首屏外图片
提供 width 和 height 避免布局偏移（CLS）
使用 AVIF/WebP 等现代格式
配合 srcset 提供多分辨率

预加载关键资源

在根布局中预加载字体和关键 CSS：

<svelte:head>
  <link rel="preload" href="/fonts/inter.woff2" as="font" crossorigin />
  <link rel="preload" href="/critical.css" as="style" />
</svelte:head>

代码分割

SvelteKit 默认按路由自动分割代码。你还可以手动使用动态导入：

const HeavyComponent = $derived.by(async () => {
  const module = await import('./HeavyComponent.svelte');
  return module.default;
});

缓存策略

在 +server.ts 或 +page.server.ts 中设置缓存头：

export const load: PageServerLoad = async ({ setHeaders }) => {
  setHeaders({
    'Cache-Control': 'public, max-age=3600, s-maxage=3600'
  });

  return { posts: await getPosts() };
};

部署示例：Cloudflare Pages

# 安装适配器 → 配置 svelte.config.js → 构建
bun add --dev @sveltejs/adapter-cloudflare
bun run build
# 使用 Wrangler CLI 部署
bunx wrangler pages deploy .svelte-kit/cloudflare

Cloudflare Pages 的构建配置（wrangler.toml）：

[build]
command = "bun run build"
directory = ".svelte-kit/cloudflare"

[env.production]
vars = { PUBLIC_API_URL = "https://api.fisherhub.cn" }

总结

本章你学会了：

三种适配器的安装与配置（Cloudflare、Static、Node）
SSR、SSG、SPA 三种渲染模式及混合使用
公共和私有环境变量的管理
图片优化、预加载、代码分割等性能优化手段
部署到 Cloudflare Pages 的完整流程

建议你从一个小项目开始实践，逐步熟悉这些概念。