Sveltepress

先看在线效果

动手搭建之前，强烈建议先打开在线 Demo：sveltepress.github.io/sveltepress/blog-demo。本页介绍的一切特性都已经在这里跑起来了。

导航栏中的 博客示例 是这份成品展示。导航栏中的 演练场 打开功能目录。「配置」「写文章」「特性」和「自定义」才是会自动启动 Blog starter 的博客主题条目。本快速上手页不是演练场条目，也没有「在演练场中打开」控件。

源码在 monorepo 中的 packages/example-blog。克隆仓库后，在仓库根目录执行 pnpm install 和 pnpm --filter @sveltepress/example-blog dev，Demo 会启动在 http://localhost:36739。

@sveltepress/theme-blog 是一款杂志风格的博客主题，自带左侧边栏、瀑布流文章网格、自动生成的单篇 OG 图片、RSS、Pagefind 搜索和 Giscus 评论。本页演示如何从零搭建一个可运行的博客。

安装

npm install --save @sveltepress/theme-blog

yarn add @sveltepress/theme-blog

pnpm install @sveltepress/theme-blog

bun add @sveltepress/theme-blog

主题由 Sveltepress Vite 插件加载：

npm install --save @sveltepress/vite

yarn add @sveltepress/vite

pnpm install @sveltepress/vite

bun add @sveltepress/vite

主题依赖 @sveltejs/adapter-static，因为它会生成完全静态的站点（预渲染 HTML、JSON、RSS 与 OG 图片）。

npm install --save @sveltejs/adapter-static

yarn add @sveltejs/adapter-static

pnpm install @sveltejs/adapter-static

bun add @sveltejs/adapter-static

Vite 构建完成后，由 Pagefind 创建本地搜索索引：

npm install --save pagefind

yarn add pagefind

pnpm install pagefind

bun add pagefind

配置 Vite

vite.config.ts

import { import blogThemeblogTheme } from '@sveltepress/theme-blog'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.defineConfig } from 'vite'

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.defineConfig({
  UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.plugins: [
    function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
      SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: import blogThemeblogTheme({
        title: stringtitle: 'My Blog',
        description: stringdescription: 'Thoughts on Svelte and the web.',
        base: stringbase: 'https://example.com',
        
author: {
    name: string;
    avatar: string;
    bio: string;
    socials: {
        github: string;
        twitter: string;
        rss: string;
    };
}author: {
          name: stringname: 'Your Name',
          avatar: stringavatar: '/avatar.png',
          bio: stringbio: '侧边栏展示的简短介绍。',
          
socials: {
    github: string;
    twitter: string;
    rss: string;
}socials: {
            github: stringgithub: 'your-handle',
            twitter: stringtwitter: 'your-handle',
            rss: stringrss: '/rss.xml',
          },
        },
        
navbar: {
    title: string;
    to: string;
}[]navbar: [
          { title: stringtitle: '首页', to: stringto: '/' },
          { title: stringtitle: '时间线', to: stringto: '/timeline/' },
          { title: stringtitle: '标签', to: stringto: '/tags/' },
        ],
      }),
    }),
  ],
})

配置 SvelteKit

svelte.config.js

import adapter from '@sveltejs/adapter-static'
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'

export default {
  extensions: ['.svelte'],
  preprocess: [vitePreprocess()],
  kit: {
    adapter: adapter({
      pages: 'dist',
      assets: 'dist',
      fallback: '404.html',
    }),
    prerender: {
      handleMissingId: 'ignore',
      handleUnseenRoutes: 'ignore',
    },
    paths: {
      base: process.env.BASE_PATH ?? '',
      relative: false,
    },
  },
  compilerOptions: {
    runes: true,
  },
}

BASE_PATH 用于在子路径下部署（例如 GitHub Pages 的项目站点）。根路径部署时保持该环境变量未设置即可。

写第一篇文章

新建 src/posts/hello-world.md：

src/posts/hello-world.md

---
title: Hello world
date: 2026-04-17
tags: [intro]
category: meta
excerpt: 博客的第一篇文章。
---

# Hello

欢迎来到我的博客。一切都是 Markdown。

自动生成的路由

下次执行 vite dev 或 vite build 时，主题会在这些文件不存在时写入它们。你可以自由编辑——脚手架只创建缺失的文件。

路径	作用
`src/routes/+layout.ts`	启用预渲染并设置 `trailingSlash: 'always'`
`src/routes/+layout.svelte`	用 `GlobalLayout` 包裹所有页面
`src/routes/+page.{server.ts,svelte}`	分页的首页
`src/routes/page/[n]/...`	第 2 页及之后的列表
`src/routes/posts/[slug]/...`	单篇文章页
`src/routes/tags/+page.svelte`	标签索引
`src/routes/tags/[tag]/...`	按标签过滤的文章
`src/routes/categories/[cat]/...`	按分类过滤的文章
`src/routes/timeline/+page.svelte`	归档时间线

构建

在 package.json 中把 Pagefind 加到构建脚本：

package.json

{
  "scripts": {
    "build": "vite build && pagefind --site dist"
  }
}

txt

pnpm build

bash

Pagefind 会为构建产物建立索引，让内置搜索弹窗（⌘K / Ctrl+K）正常工作。当前版本始终渲染 Pagefind 搜索，因此请保留这个构建后步骤。

最终的 dist/ 是一个可以部署到任意静态主机的静态站点。

当前页面

安装配置 Vite 配置 SvelteKit 写第一篇文章自动生成的路由构建