SvelteKit静态站点生成(SSG)完全指南

SvelteKit静态站点生成(SSG)完全指南

kit web development, streamlined 项目地址: https://gitcode.com/gh_mirrors/kit/kit

什么是静态站点生成

静态站点生成(Static Site Generation, SSG)是一种将网站预渲染为纯HTML、CSS和JavaScript文件的技术。与传统的服务器端渲染(SSR)不同，SSG在构建时就已经生成了所有页面，不需要在用户访问时动态生成内容。这种方式特别适合内容不频繁变化的网站，如博客、文档站点和企业官网。

为什么选择SvelteKit进行静态站点生成

SvelteKit提供了开箱即用的静态站点生成能力，通过adapter-static适配器可以轻松将你的应用转换为静态站点。相比其他静态站点生成器，SvelteKit的优势在于：

1. 基于Svelte框架，提供优秀的运行时性能
2. 支持动态路由和页面级预渲染
3. 灵活的构建配置选项
4. 现代化的开发体验

配置静态适配器

基本安装与配置

首先需要安装静态适配器：

npm install -D @sveltejs/adapter-static

然后在svelte.config.js中进行配置：

import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'build',       // 输出目录
      assets: 'build',      // 静态资源目录
      fallback: undefined,  // SPA回退页面
      precompress: false,   // 是否预压缩
      strict: true          // 是否严格模式
    })
  }
};

预渲染设置

在根布局文件中启用预渲染：

// src/routes/+layout.js
export const prerender = true;

这个设置告诉SvelteKit将所有页面预渲染为静态HTML文件。如果某些页面需要动态渲染，可以在页面级别覆盖这个设置。

关键配置选项详解

页面与资源输出目录

• pages: 指定预渲染HTML文件的输出目录
• assets: 指定静态资源(如图片、CSS、JS)的输出目录

通常这两个目录设置为相同路径即可。

SPA回退(fallback)

当需要构建单页应用(SPA)时，可以设置fallback选项：

adapter({
  fallback: '200.html'  // 或index.html/404.html
})

这会在用户访问不存在的路由时提供一个回退页面，由前端路由接管导航。

预压缩(precompress)

启用precompress会生成.br(Brotli)和.gz(Gzip)压缩版本的文件，可以显著减少传输体积：

adapter({
  precompress: true
})

严格模式(strict)

严格模式(default: true)会检查是否所有页面都被预渲染。如果确定某些页面不需要预渲染，可以关闭此检查：

adapter({
  strict: false
})

部署注意事项

路径基础(base path)

当站点部署在子路径下时，需要设置paths.base：

// svelte.config.js
export default {
  kit: {
    paths: {
      base: process.env.NODE_ENV === 'production' ? '/your-repo-name' : ''
    }
  }
}

尾斜杠(trailingSlash)

根据托管环境的不同，可能需要统一URL的尾斜杠：

// src/routes/+layout.js
export const trailingSlash = 'always'; // 或'never'/'ignore'

高级使用场景

混合预渲染与动态渲染

SvelteKit允许混合使用预渲染和动态渲染。只需在不需要预渲染的页面中设置：

// 在特定页面文件中
export const prerender = false;

条件性预渲染

对于需要根据构建时数据决定是否预渲染的页面：

export const prerender = ({ data }) => {
  return data.shouldPrerender;
};

常见问题解决

1. 404页面处理：确保为SPA模式提供适当的fallback页面
2. 路由不匹配：检查trailingSlash设置是否与托管环境匹配
3. 资源路径错误：在子路径部署时正确配置base路径
4. 预渲染失败：检查是否有动态导入或浏览器API在构建时执行

性能优化建议

1. 启用precompress以减少传输体积
2. 使用@sveltejs/adapter-static@latest获取最新优化
3. 合理设置缓存头提升二次访问速度
4. 考虑使用CDN分发静态资源

通过以上配置和优化，你可以充分利用SvelteKit的静态站点生成能力，构建出高性能、易维护的现代Web应用。

kit web development, streamlined 项目地址: https://gitcode.com/gh_mirrors/kit/kit