最近想再开一个纯静态的博客，试了一圈 Astro 主题之后选了 Fuwari。它是 saicaca 开发的开源博客模板，颜值在线、动画流畅，功能也齐全：亮暗模式、主题色调节、全站搜索、目录、RSS 都是现成的。这篇文章记录一下从零到上线的完整过程，照着做大概十分钟就能跑起来。

Fuwari 是什么

Fuwari 是一个基于 Astro 和 Tailwind CSS 的静态博客模板，主要特性：

  • 流畅的动画和页面切换效果
  • 亮色 / 暗色模式切换，主题色可在右上角调色盘实时预览
  • 基于 Pagefind 的全站全文搜索
  • 自动生成文章目录（TOC）、RSS 订阅
  • Markdown 扩展语法（如 GitHub 风格提示块）
  • 完全静态输出，随便扔到哪个托管平台都能跑

准备工作

只需要两样东西：

  1. Node.js 20 或更高版本：去官网下载 LTS 版本安装即可。
  2. pnpm 9 或更高版本：Fuwari 强制使用 pnpm 管理依赖，用 npm 或 yarn 安装会直接报错。没装过的话执行：
npm install -g pnpm

另外建议有一个 GitHub 账号，方便后面把代码存到仓库并接自动部署。

第一步：初始化项目

有两种方式，任选其一。

方式 A：脚手架命令（推荐）

pnpm create fuwari@latest

按提示输入项目名，询问「Install Dependencies」时选 Yes，「Initialize Git」按需选 Yes，完成后会自动生成项目目录并装好依赖。

方式 B：从 GitHub 模板生成仓库

打开 saicaca/fuwari 的 GitHub 仓库，点绿色的「Use this template - Generate a new repository」，在自己的账号下生成一个副本，然后克隆到本地：

git clone https://github.com/你的用户名/fuwari.git
cd fuwari
pnpm install

第二步：本地跑起来

在项目根目录执行：

pnpm dev

然后浏览器打开 http://localhost:4321 ，就能看到带示例文章的博客了。开发服务器支持热更新，改配置和文章保存后立即生效。

Windows 下如果安装依赖或启动时报 sharp 相关的错误，手动补装一下：

pnpm add sharp

第三步：修改站点配置

Fuwari 的所有个性化配置都集中在 src/config.ts 一个文件里，改这一处就够了。几个关键的配置对象：

配置项 作用 常用字段
siteConfig 站点信息 title 标题、subtitle 副标题、lang: 'zh_CN' 语言、themeColor.hue 主题色相（0-360）、banner 首页横幅图
profileConfig 侧边栏个人卡片 avatar 头像路径、name 昵称、bio 简介、links 社交链接
navBarConfig 导航栏链接 内置 Home / Archive / About，也可以加自定义链接
licenseConfig 文章版权声明 协议名称和链接，如 CC BY-NC-SA 4.0

几个小提示：

  • lang 记得改成 'zh_CN'，否则日期等格式是英文的。
  • 社交链接的图标名来自 icones.js.org，如果用了主题没预置的图标集，需要 pnpm add @iconify-json/<图标集名> 安装。
  • 部署前务必打开根目录的 astro.config.mjs，把 site 改成你的最终域名，否则 RSS 和 sitemap 里的地址是错的。

第四步：写文章

一行命令创建新文章：

pnpm new-post my-first-post

会在 src/content/posts/ 下生成 my-first-post.md，头部是 frontmatter 元信息：

---
title: 我的第一篇文章
published: 2026-08-24
description: 这是文章摘要，会显示在列表页
image: ./cover.jpg
tags: [Astro, Fuwari]
category: 技术
draft: false
---
  • published 是发布日期，列表按它排序；draft: true 的文章不会出现在正式站点里。
  • 封面图两种放法：直接把图片和 md 放同目录用相对路径引用；或者放到 public/ 下用绝对路径。
  • 正文就是标准 Markdown，代码块高亮开箱即用。

保存后切回浏览器就能看到新文章，确认没问题就可以部署了。

第五步：构建与部署

执行构建：

pnpm build

产物在 dist/ 目录——注意这一步会顺便用 Pagefind 生成搜索索引，所以本地想体验搜索功能的话要先 build 再 pnpm preview。

托管平台任选其一，全部免费额度就够用：

平台 方式
Vercel / Netlify 导入 GitHub 仓库，框架自动识别为 Astro，零配置
Cloudflare Pages 构建命令 pnpm build，输出目录 dist
GitHub Pages 仓库设置里启用 Pages，用官方 Astro Action 构建

以 Vercel 为例：新建 Project - 选择你的 fuwari 仓库 - Import，其他什么都不用填，点 Deploy 就完事了。之后每次 git push，平台都会自动重新构建上线。

日常发文流程就固定成了三步：pnpm new-post 写内容 - commit - push。

常见问题

  • 报错 only-allow pnpm：Fuwari 锁死了包管理器，老实用 pnpm。
  • 本地搜索搜不到东西：搜索索引只在 pnpm build 时生成，dev 模式下搜索是空的，属于正常现象。
  • 想要评论系统：主题本身不带评论，社区常见做法是接入 Twikoo、Waline 或 giscus，网上有不少现成的组件代码可以直接抄。
  • 如何同步上游更新：保留 fork 关系，添加 upstream 远程仓库后 git fetch upstream 再 merge 官方更新即可。

到这里，一个高颜值的个人博客就算正式开张了。剩下的事情就是换上自己的头像和横幅图，然后把写作的习惯坚持下去。