QikiiL's Blog

1. 准备环境#

需要 Node.js 和 pnpm。pnpm 通过 corepack 启用：

1
corepack enable
2
pnpm --version

2. 获取主题代码#

我把 Mizuki 的完整 git 历史拉了下来，并把它的仓库地址保留为 upstream 远程——这样以后主题更新，可以直接 git merge upstream/master 合并，不用从头再来：

1
git init -b main
2
git remote add upstream https://github.com/LyraVoid/Mizuki.git
3
git fetch upstream master
4
git reset --hard FETCH_HEAD

3. 安装依赖并配置#

1
pnpm install --frozen-lockfile

核心配置在 src/config/ 目录：站点标题、URL、语言（zh_CN）、导航栏、个人资料都在这里改。

有一个关键坑：我把博客部署在项目仓库的子路径（https://用户名.github.io/blog/）下，而主题的 astro.config.mjs 里 base 默认是 "/"。不改的话所有样式和图片都会 404：

1
base: "/blog/",

4. 本地预览与构建#

1
pnpm dev   # 注意：开启 base 后访问 http://localhost:3000/blog/
2
pnpm build # 产出 dist/，同时生成 Pagefind 搜索索引

5. 部署到 GitHub Pages#

在 GitHub 创建公开仓库后推送，Mizuki 自带的 GitHub Actions 工作流（.github/workflows/deploy.yml）会在每次 push 到 main 时自动构建，并把 dist/ 发布到 pages 分支。然后在仓库设置的 Pages 里选择从 pages 分支部署即可。

6. 开启 Giscus 评论#

Giscus 基于 GitHub Discussions，免费且无需自己跑服务器：仓库开启 Discussions、安装 giscus App，再到 giscus.app 拿到 repoId 和 categoryId 填进 src/config/commentConfig.ts 就完成了。