我用 Astro + Mizuki 搭了一个自己的博客

Sun, 18 Oct 2026 00:00:00 GMT

这个博客是从零开始搭的。这篇文章把整个过程记下来，一来以后自己回头看有个参照，二来如果有人也想搭一个，可以少走一点弯路。

为什么想自己搭一个#

起因很普通：想有个地方放自己的东西。

写过的笔记散在各种 App 里，聊天记录里也有，过一阵就找不到了。我想要的是一个自己能完全掌控、又几乎不用维护的地方——把文章写成纯文本文件存在本地，剩下的交给构建工具。

所以定下三条要求：

不写代码也能维护（我只会照着说明改配置文件）
没有数据库、没有后台、没有服务器要续费
打开要好看，毕竟是自己的地方

选型：为什么最后是 Astro + Mizuki#

先试的思路是「现成的博客框架 + 现成的主题」，因为自己写前端不现实。比较下来大致是这样：

方案	二次元主题多不多	改配置难不难	结论
Astro	最多	低	✅ 选了它
Hexo	多，但风格偏旧	低	生态在退潮
Hugo	很少	高（要改模板）	放弃
Next.js	少，基本要自建	高	放弃

关键其实不是 Astro 本身，而是好看的二次元风格主题几乎只在 Astro 生态里。这一条直接决定了其他选项全部出局。

主题选的是 Mizuki，它基于 Fuwari 改的，带有 Material Design 3 的观感，评论、搜索、RSS 这些能力都接好了，需要改的东西集中在一个目录里。

实际动手的过程#

整个搭建只有几条命令。先把主题仓库拉下来——这里用浅克隆，因为完整历史体积太大，国内网络经常传一半就断：

1
git clone --depth 1 --single-branch https://github.com/matsuzaka-yuki/Mizuki.git

然后装依赖。注意 npm 官方源在这台电脑上连不上，要换成国内镜像：

1
# .npmrc 里写一行就够
2
# registry=https://registry.npmmirror.com/
3
pnpm install

装完之后：

1
pnpm dev     # 本地预览，改文件会自动刷新
2
pnpm build   # 生成最终要发布的静态文件

pnpm dev 起来之后打开 http://localhost:3000/，看到完整的页面，这一步就成了。

改配置：其实只动一个目录#

站点身份信息全在 src/config/ 里，不用碰页面代码。比如站点名称和副标题：

1
export const siteConfig: SiteConfig = {
2
  title: "我的博客",
3
  subtitle: "记录学习与生活的点滴",
4
  siteURL: "https://www.xfengling.me/", // 换成自己的域名
5
  siteStartDate: "2026-10-17",
6
  timeZone: "Asia/Shanghai",
7
};

写文章的归类规则也很简单，只有两个分类，标签交叉索引：

1
---
2
title: 文章标题
3
published: 2026-10-18
4
description: 一句话摘要，会显示在卡片上
5
tags: [Astro, 建站]
6
category: 技术
7
draft: false
8
---

踩到的几个坑#

坑一：全局 git 配置里有失效的代理规则#

所有从 GitHub 拉代码的操作都会失败，而且报错信息完全看不出原因。最后发现是 .gitconfig 里有一条指向已经停止服务的代理的重写规则，删掉就好。

改全局配置前先备份
git config --global 的改动会影响这台机器上所有仓库。删之前先复制一份 .gitconfig 出来。

坑二：依赖下载慢到以为卡死#

第一次装依赖花了五分钟。把 npm 源换成国内镜像之后降到两分钟左右。第二次再装因为本地有缓存，就快很多了。

坑三：构建最后一步的搜索索引失败#

pnpm build 会在最后生成站内搜索索引，需要联网下载一个二进制文件，这一步在本机失败了。

1
Failed to install either of [pagefind_extended, pagefind].
2
Most likely the platform windows-x64 is not yet a supported architecture.

页面本身是全部构建成功的，只是搜索用不了。搜索属于后面单独处理的事，先放着。

现在的写作流程#

这是我最在意的部分——如果写一篇文章要折腾十分钟，我肯定坚持不下来。现在的流程是：

graph LR A[新建 md 文件] --> B[写内容] B --> C[本地预览] C --> D[git push] D --> E[自动发布]

在 src/content/posts/ 下新建一个 .md 文件
打开编辑器，在文件开头填标题、日期、分类、标签
正文用 Markdown 写
保存，浏览器里立刻能看到效果
满意了 git push，托管平台自动构建发布

晚上写东西的时候，桌上差不多就是这个样子

接下来想做的事#

把首页头图和头像换成自己的图
填一下项目、技能、时间线三个页面
域名的事情等上线实测之后再说

博客搭好只是开始，真正的部分是把东西写出来。这一篇算第一块砖。

十月，开始记录

Sun, 18 Oct 2026 00:00:00 GMT

开博客这件事我想了大概有一年。

为什么一直没开始#

理由能列出一堆：没什么值得写的、写出来也没人看、排版太麻烦、坚持不下来。

后来发现这些理由其实都在回避同一件事——怕写得难看。一旦把它当成「作品」，就永远觉得还没准备好。

前几天晚上忽然想通了：博客本来就不是作品，它更像个抽屉。写得烂也无所谓，反正抽屉里的东西不用给谁看。

这个十月#

十月是最忙也最舒服的一个月。

课表不算满，但作业都是要花整晚那种
图书馆四楼靠窗的位置很好，下午的光能照到桌子上
买了一杯奶茶会坐在那里假装学习，实际上在发呆

关于秋天
我其实不太喜欢秋天，因为太短了。但秋天好看这件事没法否认。

想在这里放什么#

不打算给这个博客定主题。目前想到的是这些：

上课学到的东西，用自己的话写一遍
折腾电脑、软件装坏了的记录
看书或者看番之后的一些碎想法
没什么理由，就是想写的

下午的光

乱七八糟但自己知道东西在哪

最后#

先写，再想写得好不好。

这是给自己定的唯一一条规矩。如果哪天翻回来发现写得幼稚，那说明我确实往前走了一点。

下一篇不知道什么时候。可能明天，可能下个月。

你好，世界

Sat, 17 Oct 2026 00:00:00 GMT

你好，世界#

这是我的第一篇博客文章。

这里现在是一段占位内容：之后我会把想写的东西放在这里——学习笔记、生活片段，或者一些折腾的记录。

博客刚搭好，慢慢来。