【超详细教程】从 0 搭建 Fuwari 博客

前言#

Fuwari 作为一款基于 Astro 框架的现代博客主题，以其简洁美观的设计和强大的功能受到了越来越多开发者的喜爱。本教程将带你从 0 开始，一步步搭建属于自己的 Fuwari 博客。

准备工作#

在开始搭建之前，我们需要准备一些必要的工具和环境：

1. 安装 Node.js#

Fuwari 基于 Astro 框架，而 Astro 需要 Node.js 环境。请确保你的系统上安装了 Node.js 18.0 或更高版本。

Windows/macOS：访问 Node.js 官网下载安装包并安装
Linux：使用包管理器安装，例如 sudo apt install nodejs npm

安装完成后，打开终端（命令提示符）运行以下命令验证安装，能够提示出来版本信息，说明安装成功：

1
node -v
2
npm -v

安装 pnpm（推荐）#

pnpm 是一个快速、节省空间的 Node.js 包管理器，推荐使用它来管理项目依赖：

1
npm install -g pnpm

注意：在 Windows 上遇到权限问题时，请以管理员身份运行命令提示符。

验证 pnpm 安装，能够提示出来版本信息，说明安装成功：

1
pnpm -v

2. 安装 Git#

Git 是版本控制系统，我们需要它来克隆 Fuwari 仓库和管理代码：

Windows：访问 Git 官网下载安装包
macOS：使用 Homebrew 安装 brew install git
Linux：使用包管理器安装，例如 sudo apt install git

验证安装：

1
git --version

3. 创建 GitHub 仓库（可选）#

如果你计划将博客部署到 GitHub Pages 或其他需要 Git 仓库的平台，建议先在 GitHub 上创建一个新的仓库。

第一步：初始化项目#

方法一：直接克隆 Fuwari 仓库#

1
cd /path/to/your/blog/folder

克隆 Fuwari 仓库：

1
git clone https://github.com/saicaca/fuwari.git
2
cd fuwari

方法二：使用 npm create vite@latest#

如果你使用的是较新版本的 npm，可以使用 npm create 命令快速初始化项目：

1
npm create vite@latest my-fuwari-blog -- --template astro
2
cd my-fuwari-blog

然后手动安装 Fuwari 主题依赖。

第二步：安装依赖#

无论使用哪种方法初始化项目，都需要安装依赖：

1
pnpm install

第三步：基本配置#

Fuwari 的配置文件位于 src/config.ts，这是我们需要重点修改的文件。

1. 站点配置#

打开 src/config.ts 文件，修改以下基本配置：

1
// 站点基本信息
2
export const siteConfig: SiteConfig = {
3
  title: "我的个人博客", // 博客标题
4
  subtitle: "分享技术与生活", // 博客副标题
5
  description: "这是一个基于 Fuwari 主题的个人博客", // 博客描述
6
  keywords: ["博客", "技术", "生活"], // 关键词
7
  language: "zh-CN", // 语言
8
  favicon: "/favicon/favicon-light-32.png", // 网站图标
9
  themeColor: "#3b82f6", // 主题颜色
10
  postPerPage: 8, // 每页显示的文章数量
11
  showNavLinks: true, // 是否显示导航链接
12
  navLinks: [
13
    { name: "首页", url: "/" },
14
    { name: "归档", url: "/archive/" },
15
    { name: "关于", url: "/about/" },
16
  ], // 导航链接
17
  postsUrl: "posts", // 文章目录
18
  showPostDate: true, // 是否显示文章日期
19
  showPostReadingTime: true, // 是否显示阅读时间
20
  showPostExcerpt: true, // 是否显示文章摘要
21
  showPostTags: true, // 是否显示文章标签
22
  showPostCategories: true, // 是否显示文章分类
23
  showPostAuthor: true, // 是否显示文章作者
24
  author: "你的名字", // 作者名称
25
  email: "your-email@example.com", // 作者邮箱
26
  github: "your-github-username", // GitHub 用户名
27
  twitter: "your-twitter-username", // Twitter 用户名（可选）
28
  avatar: "/avatar.png", // 头像路径
29
  banner: "/banner.png", // 首页横幅图片
30
  footerText: "© 2026 我的个人博客. All rights reserved.", // 页脚文本
31
  rssTitle: "我的个人博客 RSS", // RSS 标题
32
  rssDescription: "我的个人博客的 RSS 订阅", // RSS 描述
33
};

2. 主题配置#

修改主题相关配置：

1
// 主题配置
2
export const themeConfig: ThemeConfig = {
3
  accentColor: "#3b82f6", // 强调色
4
  darkMode: "system", // 深色模式：system（跟随系统）、light（浅色）、dark（深色）
5
  codeTheme: "github-light", // 代码高亮主题：github-light、github-dark、okaidia 等
6
  font: {
7
    sans: "'Inter', sans-serif", // 无衬线字体
8
    serif: "'Noto Serif SC', serif", // 衬线字体
9
    mono: "'Fira Code', monospace", // 等宽字体
10
  },
11
};

3. 评论系统配置#

Fuwari 支持多种评论系统，你可以根据需要选择并配置：

1
// 评论系统配置
2
export const commentConfig: CommentConfig = {
3
  enable: true, // 是否启用评论
4
  provider: "giscus", // 评论系统：giscus、utterances、disqus、twikoo
5
  giscus: {
6
    repo: "your-username/your-repo", // GitHub 仓库
7
    repoId: "your-repo-id", // 仓库 ID
8
    category: "Announcements", // 评论分类
9
    categoryId: "your-category-id", // 分类 ID
10
    mapping: "pathname", // 评论映射方式
11
    reactionsEnabled: "1", // 是否启用表情反应
12
    emitMetadata: "0", // 是否发送元数据
13
    inputPosition: "bottom", // 输入框位置
14
    theme: "light", // 主题
15
    lang: "zh-CN", // 语言
16
  },
17
};

第四步：创建内容#

1. 创建文章#

在 src/content/posts 目录下创建 Markdown 文件来添加文章。每个文章文件需要包含前置元数据（frontmatter）：

1
---
2
title: "文章标题"
3
description: "文章描述"
4
date: 2026-01-28
5
category: "分类"
6
tags: ["标签1", "标签2"]
7
cover: "/path/to/cover-image.jpg"
8
draft: false
9
---
10

11
# 文章内容
12

13
这里是文章的正文内容，使用 Markdown 语法编写。

2. 添加图片#

你可以在文章中使用相对路径引用图片，建议将图片放在 public 目录下，例如：

1
![图片描述](/images/image.jpg)

第五步：本地预览#

在完成基本配置和内容创建后，我们可以在本地预览博客效果：

1
npm run dev

然后打开浏览器访问终端中显示的本地地址（通常是 http://localhost:3000），你就能看到你的 Fuwari 博客了！

第六步：构建与部署#

1. 构建项目#

当你满意本地预览效果后，可以构建生产版本：

1
pnpm run build

构建完成后，生成的静态文件会存放在 dist 目录中。

2. 部署选项#

部署到 Vercel（推荐）#

登录 Vercel
点击 “New Project”
选择你的博客仓库
按照提示完成部署配置
部署完成后，Vercel 会为你生成一个域名

部署到 GitHub Pages#

构建项目：pnpm run build
安装 gh-pages 包：pnpm add -D gh-pages
在 package.json 中添加部署脚本：

1
"scripts": {
2
  "deploy": "gh-pages -d dist"
3
}

运行部署命令：npm run deploy
在 GitHub 仓库设置中，将 GitHub Pages 的源设置为 gh-pages 分支

第七步：高级自定义#

1. 添加自定义页面#

除了默认的首页、归档和关于页面，你还可以添加自定义页面：

在 src/pages 目录下创建新的 Astro 文件，例如 contact.astro
编写页面内容：

1
---
2
// 页面组件
3
---
4

5
<main>
6
  <h1>联系我</h1>
7
  <p>这是联系页面</p>
8
</main>

在 src/config.ts 中的 navLinks 添加导航链接

2. 自定义主题#

你可以通过修改 src/styles 目录下的 CSS 文件来自定义主题样式，或者在 src/config.ts 中调整主题配置。

3. 添加插件#

Fuwari 支持通过 Astro 的插件系统扩展功能。你可以在 astro.config.mjs 文件中添加插件：

1
import sitemap from "@astrojs/sitemap";
2
import tailwind from "@astrojs/tailwind";
3

4
export default defineConfig({
5
  // ...
6
  integrations: [
7
    tailwind(),
8
    sitemap(),
9
    // 添加其他插件
10
  ],
11
  // ...
12
});

常见问题与解决方案#

1. 本地预览时样式丢失#

解决方案：检查是否正确安装了依赖，尝试重新运行 pnpm install。

2. 部署后页面显示 404#

解决方案：

检查路由配置是否正确
对于 GitHub Pages，确保设置了正确的 base 路径
对于 Vercel，检查构建配置是否正确

3. 评论系统不显示#

解决方案：

确保正确配置了评论系统的参数
检查仓库权限设置
对于 giscus，确保在 GitHub 上启用了 Discussions

4. 图片不显示#

解决方案：

检查图片路径是否正确
确保图片文件已上传到正确的位置
检查文件权限

总结#

通过本教程，你已经成功从 0 搭建了一个基于 Fuwari 主题的个人博客。Fuwari 作为一款现代的 Astro 博客主题，不仅外观美观，而且功能强大，支持多种评论系统、响应式设计和丰富的自定义选项。

现在，你可以开始在你的博客上分享知识、记录生活了。随着你对 Fuwari 的使用越来越熟悉，你可以尝试更多高级自定义，让你的博客更加个性化。

祝你博客之旅愉快！

前言#

准备工作#

1. 安装 Node.js#

安装 pnpm（推荐）#

2. 安装 Git#

3. 创建 GitHub 仓库（可选）#

第一步：初始化项目#

方法一：直接克隆 Fuwari 仓库#

方法二：使用 npm create vite@latest#

第二步：安装依赖#

第三步：基本配置#

1. 站点配置#

2. 主题配置#

3. 评论系统配置#

第四步：创建内容#

1. 创建文章#

2. 添加图片#

第五步：本地预览#

第六步：构建与部署#

1. 构建项目#

2. 部署选项#

部署到 Vercel（推荐）#

部署到 GitHub Pages#

第七步：高级自定义#

1. 添加自定义页面#

2. 自定义主题#

3. 添加插件#

常见问题与解决方案#

1. 本地预览时样式丢失#

2. 部署后页面显示 404#

3. 评论系统不显示#

4. 图片不显示#

总结#

参考资料#

评论