未来之蓝 | xpfxzxc 的个人博客 - 个人学习和日常零散想法的记录空间，内容随性且不定期更新

基于 Firefly 主题的 Astro 博客部署（五）：看板娘配置

Thu, 11 Dec 2025 00:00:00 GMT

截至目前，我已经将博客站点配置得差不多了。我不仅将个人博客页面打扮得相当美观，还调整了站点信息，并启用了评论系统。整体上看，这些改动使我的博客有了独特风格，具备了相当的辨识度。

不过，硬要说还有哪些地方有违和感的话，那就是博客页面窗口左下角处的看板娘 —— 流萤了。流萤的英文名是 Firefly，她是游戏《崩坏：星穹铁道》中的角色。在我将站点里的个人头像、背景壁纸等内容改成与流萤无关的主题后，当前的看板娘形象就显得不太合适了；换句话说，有更好的看板娘可选择。

对此，我有几个选择：

保留且不改动：没有谁规定过看板娘要与博客的主题适配
禁用：在看文字内容的时候，容易被看板娘分散注意力
改用其他看板娘：显然，选择与博客主题更适配的看板娘更好

我选择“改用其他看板娘”，如果能够找到合适模型的话。再说，我之前从未有过这方面的经验，所以有兴趣去接触一下这方面的内容。

此外，目前我还没有修改过音乐播放器的配置。它的外观上与当前主题色并无明显冲突，因此我打算保持原样。

Spine 还是 Live2D？

Firefly 主题集成了 Spine 和 Live2D 的 Web 库用于渲染看板娘，分别是 Spine Web Player 和 Live2D Cubism SDK for Web 。

在 Firefly 主题中，默认启用的 Spine 看板娘为流萤，其模型源于 Bilibili 上某 UP 主免费分享；而默认禁用的 Live2D 看板娘则自带雪未来和伊莉雅两个模型。

就目前主题的默认实现而言，Spine 与 Live2D 看板娘之间的功能差异在于：Live2D 支持眼睛跟随鼠标指针移动。除此之外的其他功能，如显示、播放动画、点击、拖拽，两者基本一致。但实际上，Spine 与 Live2D 之间的差异远不限于此。

介绍

Spine 是一款专业的 2D 骨骼动画软件。制作者先将角色拆分，然后将角色看成一个有多个骨骼的骨架——等同于为角色创建一套“骨骼”系统，再将拆分的部位绑定到对应的骨骼上，每个部位上附着着图片。通过旋转、移动、缩放骨骼，来带动整个角色的动作。这样，可以实现非常流畅、富有弹性的复杂动作。

Live2D 是一种 2D 图像渲染技术，通过网格变形将一张静态的 2D 立绘“活化”，创造出具有立体感和生动表情的“伪 3D”效果。这点，可以在 Bilibili 直播上随便找间虚拟主播的直播间上体验 Live2D 效果，或者在一些二次元抽卡手游的角色展示页面上体验。制作者需要将角色分成多个图层（如脸、前发、后发、身体等），然后为每个部分建立网格和变形器。通过操控这些变形器，可以实现角色的转头、身体摆体、表情变化等。本质上是在 2D 平面上进行精细的扭曲和拉伸，因此它是天生为交互设计，参数系统可以轻松映射到外部输入。

优势对比

从上面分析来看，Spine 与 Live2D 所擅长的领域不一样。Spine 主要应用于 2D 游戏动画、广告和动画短片和任何需要复杂、可循环的动作的 2D 项目；而 Live2D 主要应用于虚拟主播（VTuber）、视觉小说、角色展示界面、二次元抽卡手游。

由此可见，对于个人博客看板娘，Live2D 是更合适、更主流的选择，因为 Live2D 看板娘能通过小动作与用户的操作进行互动，如眨眼、微笑、挥手，或者眼瞳追踪着鼠标指针移动，而不需要做出跑、跳等各种复杂动作。

顺便一提，GitHub 上有个比较知名的 Live2D 看板娘项目：Live2D Widget，可以用来快速、更好地在网页中添加 Live2D 看板娘。

::github{repo="stevenjoezhang/live2d-widget"}

还有人专门收集了一些 Live2D 模型：

::github{repo="Eikanya/Live2d-model"}

最终选择

针对我之前选择的个人头像和背景壁纸，我使用搜索引擎或者在一些网站上查找相关合适的 Spine 或 Live2D 模型。由于我之前未曾涉足过 2D 角色动画领域，所以经过一番搜寻，最终只找到了两个有用的网站：Bilibili 和模之屋。

在反复考虑后，我决定选用 Bilibili 上 SunaookamiRukari UP 主免费分享的砂狼白子 Spine 模型 作为看板娘（感谢 UP 主分享！）。该资源的目录结构如下：

Shiroko
├── NP0172_spr.atlas
├── NP0172_spr.png
├── NP0172_spr.skel
└── NP0172_spr-avatar.png

这款模型挺好看的，但老实说，它过于简单、静态——一个角色静止站立着，头顶上的光环微微上下浮动，眼睛和口型有好几种动画但是是静止的，除此之外其他部位都没有变动。

作为一个非专业的模型使用者，我只能在网上有什么就用什么。选择 Spine 还是 Live2D 模型作为看板娘，主要取决于能找到什么，以及哪个模型的质量更好。虽然我更想用 Live2D，但限于个人能力，耗费大量时间也未能找到合适的，最终只好先用着 Spine 模型。有胜于无，仅此而已。

需求

由于这次采用的看板娘本身做得比较简单，那我的需求也就定得朴素一些，不搞太复杂：

显示看板娘，其初始位置位于页面窗口的左下角
点击时，看板娘的眼睛和口型将变化，并伴随随机消息提示，一段时间后自动恢复
支持在网页窗口内自由拖拽看板娘
看板娘头上的光环始终保持上下浮动

Spine 编辑器

在后面的实操部分，会使用 Spine 编辑器对从网上下载的看板娘进行微调，并重新导出模型文件。

相关文档链接：Spine 编辑器文档。

版本

目前 Spine 编辑器的最新版本是 4.3.x，在此版本下，官网提供了三种不同的发行版供用户选择：

试用版：免费试用。总是运行最新版本的 Spine，包含了专业版的所有功能，但不支持保存项目和导出资源功能
基础版：需付费。仅支持基础功能，不包含高级功能，可以运行任何较旧的 Spine 版本
专业版：需付费。支持所有功能，可以运行任何较旧的 Spine 版本

关于编辑器各发行版支持的具体功能与区别，详见官方购买页面：购买 Spine。

鉴于目前网上可获得的破解版仅为 3.8.75 专业版。本次实操将基于此版本进行。

用户界面

默认情况下，Spine 界面的左侧是视口，右侧是层级树视图。

视口是显示骨骼、设置骨骼及制作骨骼动画的主要区域。底部的主工具栏可访问各种工具和设置。

视口左上角的图标用于在设置模式和动画模式之间切换：

设置模式用于创建和配置骨架
动画模式用于设计动画

在动画模式下，默认 Spine 的底部有摄影表视图，用于显示和编辑动画的关键帧时间点。

另外，还有一种视图比较有用：曲线图视图。这可在 Spine 窗口右上角的 视图 选择框访问该视图。曲线图可显示和编辑动画的关键帧的时间点和值。关键帧值绘制在 Y 轴上，时间绘制在 X 轴上。由此产生的曲线是一条显示了该值如何随时间变化的线。

[!NOTE] 在 4.x.x 版本下，默认 Spine 的底部有曲线图视图，旁边有一个摄影表视图标签。

在视口中，常用的基本操作有：

平移：按住鼠标右键并拖动，可在视口中平移视图
缩放：通过向上/向下滚动鼠标滚轮，可对目标区域进行放缩观察
移动/旋转模式：点击鼠标右键可切换模式。启用后，在视口中按住鼠标左键并拖动，即可控制选中骨骼或图片的移动或旋转

层级树视图

层级树视图为骨架及其包含的所有内容提供了一个层次结构视图:

骨架
- 表示可设置动画的角色或对象
- 包含骨骼、插槽、附件和其他部分
骨骼
- 构成骨架的层级化关节
- 每个骨架只能有一个根骨骼
- 其长度通常不重要
- 每个骨骼都具有旋转、平移、缩放和剪切属性
- 骨骼与骨骼之间可以有父子关系，骨骼的变换会影响其子骨骼
插槽
- 只是概念性的，没有位置，也不会绘制
- 是骨骼的子级，也是附件的容器
- 用于管理显示，在任何给定时间只有一个附件（或没有附件）可见
- 骨架的绘制顺序就是一个插槽列表
附件
- 附加在插槽上，因此骨骼变换时，附件也会变换
- 附件可以是图片或者边界框
- 可以添加到皮肤
其他部分
- 约束
- 绘制顺序
- 皮肤
- 事件
- 动画

某些层级树节点在层级树的左侧边缘可能有：

可见点：单击可见点后将显示或隐藏该项目
钥匙按钮：在动画模式下，单击该钥匙将为该项目设置一个关键帧

在层级树种选择某个项后，其属性将显示在层级树的底部。这些属性是项目中的项的配置位置。某些属性只能在选择单个节点时进行编辑。大多数属性的右上角都有三个相同的按钮，分别用于复制、重命名和删除。

纹理解包器

纹理图集由一个文件扩展名为“.atlas”的图集文件和一个或多个称为图集“页面图片”的图片文件组成。图集文件描述每个打包的较小图片在页面图片中的位置，称为图集“区域”。这些区域在图集文件中按名称引用。纹理图集可在项目导出数据时打包后可以得到。

一个纹理图集可以包含多个页面图片，从而可将应用程序的所有图片打包到单个图集中。

纹理解包器可读取纹理图集，并从中根据图集文件将一个或多个页面图片分解成多个较小的图片。

打开操作路径：Spine 标志(左上角) → 主菜单 → 纹理解包器。

Spine Web Player

要在 Firefly 主题中通过 Spine Web Player 渲染模型。需完成以下工作：准备好模型的资源文件，选择适配的 Spine Web Player 版本，且在必要时使用 Spine 编辑器重新导出资源文件。

资源文件

从网上下载下来的 Spine 模型资源文件，必须包含三个文件：

骨骼数据文件
- 包含了骨骼结构、动画、约束、皮肤等信息，但不包含图片
- 格式：.json 或 .skel（二进制格式）
图集文件
- 记录了角色所有拆分散图是如何从一张（或多张）大图中拼接出来的
- 格式：.atlas，一个纯文本文件，里面定义了：
  - 使用了哪张（些）大图（.png）
  - 每个小部件（如“左手”、“头部”、“武器”）在大图中的精确位置（x，y，width，height）
  - 以及其他渲染信息（如旋转、偏移等）
纹理文件
- 一张或多张“图集大图”，由 Spine 编辑器自动将拆分好的所有小部件打包生成
- 格式：.png（最常用）
- 例如：一个角色可能只有一张 role1.png，它里面就包含了这个角色的所有身体部件

版本

Spine Web Player 的版本号（主版本号.次版本号）必须与用来导出 skeleton 和 atlas 的 Spine 编辑器版本相匹配。用来导出的 Spine 编辑器版本会被记录在导出来的骨骼数据文件里，不管是 JSON 格式还是二进制格式，都可以借助 VSCode 打开后轻易地看出来。例如：

{"skeleton":{"hash":"lzvNuUiXxTkT73S+7cJC27oo7Q0","spine":"3.8.75","x":-290.8,...

上面是某个模型的 JSON 格式的骨骼数据文件内容，其中，spine 字段的值就是用来导出的 Spine 编辑器版本，这表明应该用 3.8 版本的 Spine Web Player 去加载该模型。

重导出

有时从网上下载了模型资源文件，预览后发现有些不太满意的地方，或者想调整下导出资源时的关键设置，如图片资源更新，动画调整，输出格式调整，图集设置调整等。调整后，重新导出令人满意的“核心三件套”：骨骼数据文件、图集文件和纹理大图。

如果下载的资源还附带了 Spine 项目文件 .spine，那重导出的过程就很简单。但要是没有附带了 Spine 项目文件 .spine，那可能没那么容易调整了。幸运的是，仅凭骨骼数据文件、图集文件和纹理大图，在大多数情况下是可以还原出可用的 Spine 项目文件的。可以还原的部分有：

骨骼结构、插槽、附件
动画数据
纹理与图集映射

有些部分内容没法还原。不管怎样，能够还原出 Spine 项目文件的完整程度主要取决于之前导出“核心三件套”的完整程度。

API 中关键概念

RGBA8888

RGBA8888 是一种像素颜色存储格式，用红（R）、绿（G）、蓝（B）、透明度（A）四个通道存储颜色，“8888”则表示每个通道占用 8 比特。值得注意的是，A 实际代表“不透明度”而不是“透明度”，也就是说 A=0 是完全透明，A=255 是完全不透明。例如：0xFF0000FF 标识不透明的红色（即 R=255, G=0, B=0, A=255）。

预乘 Alpha

正如字面意思，预乘 Alpha（Premultiplied Alpha）就是让 RGB 通道预先与 A 通道相乘，A 通道仍独立存储。官方建议对所有 Spine Web Player 需显示的资产均使用预乘 Alpha，它减少了不使用预乘 Alpha 时可能出现的伪影和接缝问题。

视口

在 Spine Web Player 中，视口是指骨架所在的世界坐标空间中的一个矩形区域，再加上填充量。

默认情况下，播放器会根据动画边界框并在四周加上默认 10% 的填充自动生成一个视口。在初始化播放器的时候，可以传入 viewport 字段来配置全局视口或动画专属视口。

viewport 字段接受以下子字段：

x、y: 指定视口左下角在骨架的世界坐标空间中的位置
width、height：指定视口的尺寸
padLeft、padRight、padTop、padBottom：指定要添加到视口各边的填充量
animations：为特定动画指定专属的视口设置

在 Spine 的二维视图中，X 轴是水平轴（从左到右），Y 轴是垂直轴（从下到上）。

不管使用什么样的视图，播放器会保持视口长宽比，然后将视口嵌入到播放器的可用空间中。这过程中可能会保持长宽比缩放视口的显示内容，最终显示在播放器的内容可能溢出视口范围。为了方便调试，可以通过指定 debugRender 字段来可视化视口。

轨道

轨道（Track）用于分层应用动画功能。每个轨道都存储了一个动画和其播放参数，并通过一个从零开始的编号进行索引，该编号在运行时对应其内部数组下标。系统会按照轨道编号从小到大的顺序，依次应用各个轨道上的动画。

多轨道设计使得角色的各个部位可以独立播放动画。通过分别控制各轨道上的动画，能够复用动画资源，并动态组合出复杂的动作。例如，要创建“移动中射击”的动画，只需在轨道 0 上设置脚部移动动画，在轨道 1 上设置手臂射击动画，两者同时播放即可实现。

API 中的一些类

尽管 Spine Web Player 在运行时运用到了很多类，但对于我的需求来说，只有几个类需要稍微了解一下。

Animation 就是动画实例，存储着动画的一个时间轴的列表。AnimationState 相当于动画的“总导演”，控制和管理着动画的播放。TrackEntry 是轨道条目，存储着动画播放的设置和其他状态。

AnimationState 管理着多个轨道插槽。每个轨道插槽都是一个双向队列，管理着多个 TrackEntry，指明了动画播放顺序。每个 TrackEntry 存储着应用于该轨道条目的 Animation。

就我的需求而言，除了初始化播放器的必要调用外，仅需使用 AnimationState 的 setAnimation ( int trackIndex, string animationName, bool loop): TrackEntry 方法就足够了。

Demo

由于直接修改 Firefly 主题源码涉及代码段较长且分散，不利于逐步讲解，因此我将首先实现一个简单的 Demo。此外，在前期用较短代码实现核心功能，即使出了问题也容易定位和调试，之后再将验证过的方案集成到主题中。

根据之前列出的看板娘需求，以及目前主题源码中看板娘的实现，Demo 要实现的功能有：

显示看板娘
点击时，看板娘的眼睛和口型将变化，一段时间后自动恢复
看板娘头上的光环始终保持上下浮动

剩余的需求无需在 Demo 中实现，因为它们要么已被主题直接支持，要么只需简单配置即可满足。

1. 查看模型版本

在引入 Spine Web Player 到页面前，需要先确认导出模型文件的 Spine 编辑器版本。这是确保运行时兼容的关键步骤。

用 VSCode 打开先前下载的模型资源文件夹中的 NP0172_spr.skel 文件，在弹出的警告窗口中点击 Open Anyway 按钮，并在顶部选择 Text Editor 项。打开后，在第一行中可看到 3.8.96 字样。由此可知，该看板娘是由 Spine 编辑器 3.8.96 版本导出的。

2. 引入 Spine Web Player

Spine 运行时版本号使用 majar.minor 格式。在搜索引擎和 CDN 网站上难以搜到 Spine Web Player 3.8 的 JavaScript 和 CSS 资源链接。不过，最终还是在 Spine 运行时 GitHub 存储库中找到了 3.8 版本构建后的 build/spine-player.js 文件、构建前的 player/src/Player.ts 文件和 player/css/spine-player.css 文件。之后，引入的时候要用 spine-player.js 文件，而在参考 API 的时候要查阅 Player.ts 文件，毕竟官网 Spine 运行时 API 文档是基于最新版本 4.3.x 的。

创建 spine-web-player-demo 目录，接下来在该目录中创建以下文件与子目录结构：

spine-web-player-demo
├── server.js
└── public
    ├── index.html
    ├── NP0172_spr.atlas
    ├── NP0172_spr.png
    ├── NP0172_spr.skel
    ├── spine-player.css
    └── spine-player.js

出于安全考虑，大多数现代浏览器在 file:// 上下文中不允许通过 fetch 或 XMLHttpRequest 加载本地文件，因此需要搭建一个本地服务器：

const http = require('http');
const fs = require('fs');
const path = require('path');

const PORT = 3000;
const ROOT_DIR = './public';

// MIME 类型映射
const MIME = {
  '.js': 'text/javascript',
  '.css': 'text/css',
  '.json': 'application/json',
  '.png': 'image/png',
  '.skel': 'application/octet-stream',
  '.atlas': 'text/plain; charset=utf-8',
  '.html': 'text/html'
};

const server = http.createServer((req, res) => {
  // 默认首页
  let filePath = path.join(ROOT_DIR, req.url === '/' ? 'index.html' : req.url);

  // 获取扩展名
  const ext = path.extname(filePath).toLowerCase();
  const contentType = MIME[ext] || 'application/octet-stream';

  // 判断是否用文本模式（utf8）读取
  const isText = ['.js', '.css', '.json', '.atlas', '.html'].includes(ext);

  fs.readFile(filePath, isText ? 'utf8' : null, (err, data) => {
    if (err) {
      res.writeHead(404);
      res.end('404');
    } else {
      res.writeHead(200, { 'Content-Type': contentType });
      res.end(data);
    }
  });
});

server.listen(PORT, () => {
  console.log(`Local test server running at http://localhost:${PORT}`);
});

将 Spine Web Player 的 JavaScript 和 CSS 文件引入到页面：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Spine Web Player Demo</title>
  <link rel="stylesheet" href="spine-player.css">
</head>
<body>
  <script src="spine-player.js"></script>
  
</body>
</html>

3. 显示看板娘

参考 Spine Web Player 文档和 Player.ts 文件源码，将播放器嵌入到页面上。在 <body> 标签里：

<div id="player-container" style="width: 640px; height: 480px;"></div>

<script src="spine-player.js"></script>
<script>
  new spine.SpinePlayer("player-container", {
    skelUrl: "NP0172_spr.skel",
    atlasUrl: "NP0172_spr.atlas",
    showControls: true,
    // 背景透明
    alpha: true,
    backgroundColor: "#00000000",
    premultipliedAlpha: true,
  });
</script>

运行命令：

node server.js

通过 showControls 配置属性来显示播放器的控件，这样可以手动切换动画。

在浏览器中访问 http://localhost:3000，观察到看板娘的脸部显示存在异常，出现了较大面积的空白区域：

尝试将 premultipliedAlpha 字段的值设置成 false：

结果看板娘的脸部显示仍然存在异常：前部头发偏白色。这可能是因为作者用 Spine 编辑器导出资源时，没启用“预乘 Alpha”。

可以使用 ImageMagick 工具快速解决该问题：

magick public/NP0172_spr.png -channel RGB -fx "u*a" public/NP0172_spr.png

针对图集的 RGB 通道，将像素值(u)乘以透明度(a)，A 通道保持不变。这完全符合 Spine 的预乘定义。

仍然将 premultipliedAlpha 字段的值为 true，再次测试，此时看板娘的显示正常。

4. 还原 Spine 项目

现在，当页面上播放器显示出看板娘时，就会自动开始播放动画。

通过底部控件右方的动画选择器，可以手动切换当前活动的动画。在反复切换不同动画后发现存在以下问题：

切换动画时，模型会轻微上下位移
看板娘头上的光环没有浮动（如 01 动画）或者浮动幅度过小（如 Idle_01 动画）

至于轻微上下位移的问题，是由于初始化播放器时未通过 viewport 字段手动指定视口位置和尺寸，播放器此时会自动计算并设置视口。若需手动指定 viewport 字段，则需要提前获取骨架所在世界坐标空间中的位置和尺寸。

使用 Spine 编辑器就能很好地解决这两个问题，所以接下来要先还原出 Spine 项目。

打开 Spine 编辑器后，点击 Spine 标志(左上角) → 主菜单 → 导入数据 导入 NP0172_spr.skel 骨骼数据：

导入成功后，会提示贴图缺失：

所以接下来要导入贴图，点击 Spine 标志(左上角) → 主菜单 → 纹理解包器，图集文件选择 NP0172_spr.atlas，输出文件夹路径随意，不勾选 非预乘 alpha 选项：

点击 解开 按钮。解包成功后，在输出文件夹里会发现纹理文件被拆成多张贴图。

在右侧层级树视图中选择 动画 节点，其属性将显示在层级树视图的底部，然后选择刚才的输出文件夹路径作为图片文件的路径：

这样，就成功通过模型资源文件还原得到 Spine 项目文件了。

5. 分离并修改光环动画

为了使看板娘头顶上的光环浮动效果更明显，可以加大光环上下浮动的距离。同时，为了避免动画切换时，光环出现“瞬移”现象，有必要将光环浮动动画独立出来。这样，点击后看板娘的眼睛和口型发生变化时，光环浮动动画不会受到影响。

在 Spine 编辑器中，点击视口左上角的图标切换到动画模式，然后展开层级树视图中动画节点，接着依次展开 root > PC_Layer > halo 节点。

可以通过点击动画节点的子节点左边的可见点来显示或隐藏对应的动画，但每次只能显示一个。

显示动画后，选中 root 节点或其子节点，就能在左侧视口底部的摄影表视图中看见该节点的关键帧变化，同时视图底部的主工具栏会显示旋转、移动、缩放、倾斜等参数。按住 Ctrl 键可以进行多选。按 Esc 键可取消选中这些节点，此时摄影表视图中会显示当前动画所涉及到的节点及其所有关键帧。

拖动摄影表视图里的时间轴或者点击 ▶ 按钮，可以播放当前显示中的动画。

经过反复操作可以发现：

光环在 halo 插槽中
仅 Idle_01 动画里有光环的浮动效果，PC_Layer 骨骼有轻微移动
其他动画里光环没有浮动效果，PC_Layer 骨骼没有移动，但有眼睛和口型的变化

为了实现动画分层，需要创建一个单独用于光环的 halo_float 动画：

在层级树视图中选中 Idle_01 动画节点，点击底部属性右下第一个按钮来复制该节点
将新的动画节点重命名为 halo_float

紧接着将光环上下浮动效果调整得更明显：

选中 halo 骨骼节点，在摄影表视图里选中第 50 帧，在主工具栏中，将移动字段的 1251.8 改成 1274.3
点击旁边的红色钥匙按钮，设置一个移动的关键帧

最后将多余的动画效果删除，注意不要遗漏第 0 帧的关键帧：

选中 PC_Layer 骨骼节点，在摄影表视图里将 PC_Layer 骨骼行里的 移动 属性行中的关键帧全部删除
点击 Idle_01 动画节点左边的可见点，然后选中 halo 骨骼节点，在摄影表视图中将 halo 骨骼行的所有属性行中的关键帧全部删除

6. 导出资源

点击 Spine 标志(左上角) → 主菜单 → 导出...，数据 字段选择 JSON，输出文件夹路径随意，纹理图集 字段勾选 打包 → 选择 附件：

然后点击 打包设置 按钮弹出 纹理打包器设置 窗口，勾选 输出 部分里的 预乘 Alpha 选项：

点击 确定 按钮返回到上一个窗口，接着点击 导出 按钮导出资源。

导出资源完毕后，确保 public 目录下至少要包含：

public
├── index.html
├── NP0172_spr.atlas
├── NP0172_spr.json
├── NP0172_spr.png
├── spine-player.css
└── spine-player.js

7. 修改 Spine 版本号

由于当前已改用 JSON 格式的骨骼数据文件，因此代码中在指定骨骼数据文件路径时，应当使用 jsonUrl 字段替代原先的 skelUrl 字段：

-skelUrl: "NP0172_spr.skel",
+jsonUrl: "NP0172_spr.json",

此时尝试运行会发现，Spine 播放器提示错误：

Error: could not load skeleton .json.
Error: Unsupported skeleton data, please export with a newer version of Spine.

用 VSCode 编辑 NP0172_spr.json 文件，将开头的 spine 字段修改：

- {"skeleton":{"hash":"yYnv88Uea00W/bB6gcmM/ZQmLSA","spine":"3.8.75"... }}
+ {"skeleton":{"hash":"yYnv88Uea00W/bB6gcmM/ZQmLSA","spine":"3.8.99"... }}

再次尝试运行，这次可正常显示了。经测试，实际上可以将它改成任意 3.8.x，只要不是 3.8.75 即可。

8. 测量视口区域

为了避免动画切换时可能出现的轻微位移现象，可以预先在代码中固定好视口的位置和尺寸。虽然 Idle_01 动画中的看板娘实际上会移动约 2.5 像素，但这一变化在视觉上很难被察觉。

通过单击视口中缩放滑块上方的标尺按钮可以显示标尺。标尺单位采用世界坐标，与尚未缩放的图片的像素相对应。标尺上，每大格代表 500 像素。每个大格均分为 8 小格，故每小格代表 62.5 像素。

初始化播放器时，为了自定义 viewport 字段的值，需要用标尺去分别测量看板娘左下角处的位置和看板娘尺寸。这结果大概分别为 (-300,-750) 和 625×2150。

viewport: {
  padLeft: 0,
  padRight: 0,
  padTop: 0,
  padBottom: 0,
  x: -300,
  y: -750,
  width: 625,
  height: 2150,
  debugRender: true,
}

9. 添加交互

使用 AnimationState 的 setAnimation ( int trackIndex, Animation animation, bool loop): TrackEntry 方法可以实现动画分层：

轨道 0：用于播放 Idle_01 或眼睛和口型变化的动画
轨道 1：持续循环播放 halo_float 动画

经过分层处理后，动画效果更加自然。即使看板娘的表情和口型发生变化，其头顶光环的浮动位置也不会被重置。

还有，看板娘眼睛和口型发生变化后，在经过一段时间（如 1500ms）后会恢复原状：

showControls: false, // 隐藏控件
animation: "Idle_01", // 初始播放动画
success: (player) => {
  player.animationState.setAnimation(1, "halo_float", true);

  isClickable = true;
  document.getElementById("player-container").addEventListener("click", () => {
    if (!isClickable) return;

    isClickable = false;
    const animations = ["00", "01", "02", "04", "05", "06", "07", "08", "99"];
    const randomIndex = Math.floor(Math.random() * animations.length);
    const selectedAnimation = animations[randomIndex];
    player.animationState.setAnimation(0, selectedAnimation, true);
    setTimeout(() => {
      player.animationState.setAnimation(0, "Idle_01", false);
      isClickable = true;
    }, 1500);
  });
},

至此，本 Demo 就实现完毕了。

修改源码

一旦将 Demo 实现出来后，就能够快速地修改 Firely 主题源码去实现之前提到的完整需求了。

1. 更换模型文件

Firefly 主题的 public/pio/models/spine 目录存放着 Spine 看板娘的数据文件。删除该目录下的 firefly 目录，然后新建一个名为 shiroko 的目录，并将之前导出的资源文件复制到 shiroko 目录中。

spine
└── shiroko
    ├── NP0172_spr.atlas
    ├── NP0172_spr.json
    └── NP0172_spr.png

2. 更换 JavaScript 和 CSS 文件

目前，Spine Web Player 所需的 JavaScript 和 CSS 文件存放在主题 public/pio/static 目录中，对应文件名分别为 spine-player.min.js 和 spine-player.min.css。

当前 Firefly 主题源码引入的 Spine Web Player 版本为 4.2.x，而用于导出看板娘的 Spine 编辑器版本为 3.8.75。为保持版本兼容性，需要将相关文件替换为对应的 3.8 版本。

操作时要注意：

使用 Spine Web Player 3.8 版本的官方 spine-player.js 和 spine.player.css 文件
分别通过 Minify JS Online 和 Minify CSS Online 对代码进行压缩
将压缩后的内容分别覆盖至现有的 spine-player.min.js 和 spine-player.min.css 文件

3. 修改配置类型文件

由于主版本号不同，之间的 API 定义可能存在差异。此外，当前的看板娘配置类型定义也较为粗糙，有必要进一步优化调整。

主题的配置类型都定义在 src/types/config.ts 文件中。将 Spine 看板娘配置类型的定义修改为：

// Spine 看板娘配置
export type SpineModelConfig = {
  enable: boolean; // 是否启用 Spine 看板娘
  model: {
-    path: string; // 模型文件路径 (.json)
-    scale?: number; // 模型缩放比例，默认1.0
-    x?: number; // X轴偏移，默认0
-    y?: number; // Y轴偏移，默认0
-  };
+    path: string; // 模型文件路径 (.json) 或 (.skel)
+  };
+  atlas: {
+    path: string; // 模型纹理文件路径 (.atlas)
+  };
+  premultipliedAlpha?: boolean; // 是否使用预乘Alpha，默认true
  position: {
    corner: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // 显示位置
    offsetX?: number; // 水平偏移量，默认20px
    offsetY?: number; // 垂直偏移量，默认20px
  };
-  size: {
+  size?: {
    width?: number; // 容器宽度，默认280px
    height?: number; // 容器高度，默认400px
-  };
+    zoom?: number; // 缩放比例，默认1.0
+  };
+  viewport?: {
+    x?: number; // 视口X坐标
+    y?: number; // 视口Y坐标
+    width?: number; // 视口宽度
+    height?: number; // 视口高度
+    padLeft?: string | number; // 视口左侧内边距
+    padRight?: string | number; // 视口右侧内边距
+    padTop?: string | number; // 视口上侧内边距
+    padBottom?: string | number; // 视口下侧内边距
+    debugRender?: boolean; // 是否启用调试渲染
+  };
+  animations: {
+    initial: string; // 初始动画
+    idle: string[]; // 待机动画列表
+    idleInterval?: number; // 待机动画切换间隔（毫秒），默认10000
+    persistent: string[]; // 持续播放的动画列表
+  },
  interactive?: {
    enabled?: boolean; // 是否启用交互功能，默认true
    clickAnimations?: string[]; // 点击时随机播放的动画列表
    clickMessages?: string[]; // 点击时随机显示的文字消息
    messageDisplayTime?: number; // 文字显示时间（毫秒），默认3000
-    idleAnimations?: string[]; // 待机动画列表
-    idleInterval?: number; // 待机动画切换间隔（毫秒），默认10000
  };
  responsive?: {
    hideOnMobile?: boolean; // 是否在移动端隐藏，默认false
    mobileBreakpoint?: number; // 移动端断点，默认768px
  };
  zIndex?: number; // 层级，默认1000
  opacity?: number; // 透明度，0-1，默认1.0
};

引入 zoom 字段可以灵活调整看板娘容器的显示尺寸，且缩放效果相较于其他实现方式更为平滑流畅。

4. 修改配置文件

Spine 看板娘相关配置在 src/config/pioConfig.ts 文件中，修改为：

-// Spine 看板娘配置
+// Spine 看板娘配置（版本 3.8）
export const spineModelConfig: SpineModelConfig = {
-  enable: false, // 启用 Spine 看板娘
+  enable: true, // 启用 Spine 看板娘
  model: {
    // Spine模型文件路径
-    path: "/pio/models/spine/firefly/1310.json",
-    scale: 1.0, // 模型缩放比例
-    x: 0, // X轴偏移
-    y: 0, // Y轴偏移
-  },
+    path: "/pio/models/spine/shiroko/NP0172_spr.json",
+  },
+  atlas: {
+    // Spine模型纹理文件路径
+    path: "/pio/models/spine/shiroko/NP0172_spr.atlas",
+  },
+  premultipliedAlpha: true, // 使用预乘Alpha
  position: {
    // 显示位置 bottom-left，bottom-right，top-left，top-right，注意：在右下角可能会挡住返回顶部按钮
    corner: "bottom-left",
    offsetX: 0, // 距离右边缘0px
    offsetY: 0, // 距离底部0px
  },
  size: {
-    width: 135, // 容器宽度
-    height: 165, // 容器高度
+    width: 625, // 容器宽度
+    height: 2150, // 容器高度
+    zoom: 0.18, // 容器缩放比例
+  },
+  viewport: {
+    padLeft: 0,
+    padRight: 0,
+    padTop: 0,
+    padBottom: 0,
+    x: -300,
+    y: -750,
+    width: 625,
+    height: 2150,
+    debugRender: false,
+  },
+  animations: {
+    initial: "Idle_01", // 初始动画
+    idle: ["Idle_01"], // 待机动画列表
+    idleInterval: 8000, // 待机动画切换间隔（8秒）
+    persistent: ["halo_float"] // 持续播放的动画列表
  },
  interactive: {
    enabled: true, // 启用交互功能
-    clickAnimations: [
-      "emoji_0",
-      "emoji_1",
-      "emoji_2",
-      "emoji_3",
-      "emoji_4",
-      "emoji_5",
-      "emoji_6",
-    ], // 点击时随机播放的动画列表
-    clickMessages: [
-      "你好呀！我是流萤~",
-      "今天也要加油哦！✨",
-      "想要一起去看星空吗？🌟",
-      "记得要好好休息呢~",
-      "有什么想对我说的吗？💫",
-      "让我们一起探索未知的世界吧！🚀",
-      "每一颗星星都有自己的故事~⭐",
-      "希望能带给你温暖和快乐！💖",
+    clickAnimations: ["00", "01", "02", "04", "05", "06", "07", "08", "99"], // 点击时随机播放的动画列表
+    clickMessages: [ // ---
+      "欢迎来到这个小小的空间~",
+      "今天也请享受探索的乐趣吧！",
+      "发现什么有趣的内容了吗？",
+      "要喝杯茶休息一下吗？",
+      "希望你能在这里找到需要的信息",
+      "阳光正好，是个适合阅读的日子",
+      "每个角落都藏着小小惊喜",
+      "感谢你的到访，愿你有个美好的一天",
+      "这里记录着思考和成长的痕迹",
+      "慢慢来，享受这段时光",
    ], // 点击时随机显示的文字消息
    messageDisplayTime: 3000, // 文字显示时间（毫秒）
-    idleAnimations: ["idle", "emoji_0", "emoji_1", "emoji_3", "emoji_4"], // 待机动画列表
-    idleInterval: 8000, // 待机动画切换间隔（8秒）
  },
  responsive: {
    hideOnMobile: true, // 在移动端隐藏
    mobileBreakpoint: 768, // 移动端断点
  },
  zIndex: 1000, // 层级
  opacity: 1.0, // 完全不透明
};

这里也同时调整了点击看板娘时随机显示的文字消息内容。

5. 修改看板娘展示组件

src/components/widget/SpineModel.astro 文件为看板娘的核心展示组件。根据新版配置做适配修改，以确保所有配置项能够正确应用。

修改点 1：调整 HTML 元素属性

<!-- Spine Web Player CSS 将在 script 中动态加载 -->{
  spineModelConfig.enable && (
    <div
+      id="spine-model-container"
+      style={`
+      position: fixed;
+      ${spineModelConfig.position.corner.includes("right") ? "right" : "left"}: ${spineModelConfig.position.offsetX}px;
+      ${spineModelConfig.position.corner.includes("top") ? "top" : "bottom"}: ${spineModelConfig.position.offsetY}px;
-      width: ${spineModelConfig.size.width}px;
-      height: ${spineModelConfig.size.height}px;
      pointer-events: auto;
      z-index: 1000;
    `}
    >
-      <div id="spine-player-container" style="width: 100%; height: 100%;" />
+      <div
+        id="spine-player-container"
+        style={`
+          width: ${spineModelConfig?.size?.width || 280}px;
+          height: ${spineModelConfig?.size?.height || 400}px;
+          zoom: ${spineModelConfig?.size?.zoom || 1};
+        `} />
      <div id="spine-error" style="display: none;" />
    </div>
  )
}

修改点 2：更正 Altas 路径

- <script define:vars={{ spineModelConfig, modelPath: url(spineModelConfig.model.path), atlasPath: url(spineModelConfig.model.path.replace(".json", ".atlas")), cssPath: url("/pio/static/spine-player.min.css"), jsPath: url("/pio/static/spine-player.min.js") }}>
+ <script define:vars={{ spineModelConfig, modelPath: url(spineModelConfig.model.path), atlasPath: url(spineModelConfig.atlas.path), cssPath: url("/pio/static/spine-player.min.css"), jsPath: url("/pio/static/spine-player.min.js") }}>

修改点 3：修改 CDN 链接

源代码目前优先尝试从 CDN 获取 Spine Web Player 4.2 版本的 JavaScript 和 CSS 文件；若获取失败，则回退到本地服务器资源。由于目前尚未找到 3.8 版本的公开 CDN 地址，为了简化修改并避免大规模调整代码，我将原 CDN 链接直接替换为指向本地服务器的相同文件路径。这样，将始终从本地加载 3.8 版本的文件，虽然可能在回退逻辑下触发两次本地请求，但整体逻辑保持简洁、易于维护。

- cdnLink.href =
-   "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/spine-player.min.css";
+ cdnLink.href = cssPath;

- script.src =
-   "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/iife/spine-player.min.js";
+ script.src = jsPath;

修改点 4：调整初始化播放器的参数

// 创建 SpinePlayer
const player = new window.spine.SpinePlayer("spine-player-container", {
-  skeleton: modelPath,
-  atlas: atlasPath,
-  animation: "idle",
+  jsonUrl: modelPath.endsWith(".json") ? modelPath : null,
+  skelUrl: modelPath.endsWith(".skel") ? modelPath : null,
+  atlasUrl: atlasPath,
+  animation: spineModelConfig.animations.initial,
  backgroundColor: "#00000000", // 透明背景
  showControls: false, // 隐藏控件
  alpha: true,
-  premultipliedAlpha: false,
+  premultipliedAlpha: spineModelConfig.premultipliedAlpha || true,
+  viewport: spineModelConfig.viewport,
  /* ... */
});

修改点 5：调整动画逻辑

目前，看板娘的动画播放是基于单轨道机制实现的。为了支持动画分层播放功能，接下来需要将代码改成基于多轨道的架构：

轨道 0（主动画层）：用于循环播放待机动画和响应点击交互
轨道 1 及以上（附加动画层）：持续播放背景或装饰性动画，实现动画叠加效果

这一调整将实现与之前 Demo 版本一致的分层动画效果。

success: (player) => {
  console.log("🎉 Spine model loaded successfully!");

  // 保存播放器实例引用
  window.spinePlayerInstance = player;
+  
+  // 播放持续动画
+  spineModelConfig.animations.persistent.forEach((anim, i) => {
+    try {
+      player.animationState.setAnimation(i + 1, anim, true);
+    } catch (e) {
+      console.warn("Failed to play persistent animation:", e);
+    }
+  });

  // 初始化完成后设置默认姿态
  setTimeout(() => {
    if (player.skeleton) {
      try {
        player.skeleton.updateWorldTransform();
        player.skeleton.setToSetupPose();
      } catch (e) {
        console.warn("Error positioning skeleton:", e);
      }
    }
  }, 500);
+
+  // 设置待机动画循环
+  if (spineModelConfig.animations.idle.length > 1) {
+    setInterval(() => {
+      try {
+        const idleAnims =
+          spineModelConfig.animations.idle;
+        const randomIdle =
+          idleAnims[Math.floor(Math.random() * idleAnims.length)];
+        player.animationState.setAnimation(0, randomIdle, true);
+      } catch (e) {
+        console.warn("Failed to play idle animation:", e);
+      }
+    }, spineModelConfig.animations.idleInterval || 10000);
+  }

  // 设置交互功能
  if (spineModelConfig.interactive.enabled) {
    const canvas = document.querySelector(
      "#spine-player-container canvas"
    );
    if (canvas) {
      canvas.addEventListener("click", () => {
        // 防抖处理：防止重复点击
        const currentTime = Date.now();
        if (isClickProcessing || currentTime - lastClickTime < 500) {
          return; // 500ms 内重复点击忽略
        }

        isClickProcessing = true;
        lastClickTime = currentTime;

        // 随机播放点击动画
-        const clickAnims =
-          spineModelConfig.interactive.clickAnimations ||
-          (spineModelConfig.interactive.clickAnimation
-            ? [spineModelConfig.interactive.clickAnimation]
-            : []);
+        const clickAnims = spineModelConfig.interactive.clickAnimations

        if (clickAnims.length > 0) {
          try {
            const randomClickAnim =
              clickAnims[Math.floor(Math.random() * clickAnims.length)];
-            player.setAnimation(randomClickAnim, false);
+            player.animationState.setAnimation(0, randomClickAnim, false);

            // 动画播放完成后回到待机状态
            setTimeout(() => {
              const idleAnims =
-                spineModelConfig.interactive.idleAnimations;
+                spineModelConfig.animations.idle;
              const randomIdle =
                idleAnims[Math.floor(Math.random() * idleAnims.length)];
-              player.setAnimation(randomIdle, true);
+              player.animationState.setAnimation(0, randomIdle, true);
            }, 2000);
          } catch (e) {
            console.warn("Failed to play click animation:", e);
          }
        }

        // 显示随机消息
        const messages = spineModelConfig.interactive.clickMessages;
        if (messages && messages.length > 0) {
          const randomMessage =
            messages[Math.floor(Math.random() * messages.length)];
          showMessage(randomMessage);
        }

        // 500ms 后重置防抖标志
        setTimeout(() => {
          isClickProcessing = false;
        }, 500);
      });
-
-      // 设置待机动画循环
-      if (spineModelConfig.interactive.idleAnimations.length > 1) {
-        setInterval(() => {
-          try {
-            const idleAnims =
-              spineModelConfig.interactive.idleAnimations;
-            const randomIdle =
-              idleAnims[Math.floor(Math.random() * idleAnims.length)];
-            player.setAnimation(randomIdle, true);
-          } catch (e) {
-            console.warn("Failed to play idle animation:", e);
-          }
-        }, spineModelConfig.interactive.idleInterval);
-      }
    }
  }

  /* ... */
}

最后，访问 http://localhost:3000/，测试并确认各项功能正常。

收尾

提交更改并推送至线上

git rm -r public/pio/models/spine/firefly
git add public/pio/models/spine/shiroko
git add public/pio/static/spine-player.min.css
git add public/pio/static/spine-player.min.js
git add src/components/widget/SpineModel.astro
git add src/config/pioConfig.ts
git add src/types/config.ts
git commit -m "chore: 更换看板娘为 shiroko 并适配 Spine Web Player 3.8" -m "- 删除原看板娘 firefly，新增 看板娘 shiroko" -m "- 将 Spine Web Player 从 4.2 替换为 3.8" -m "- 调整看板娘配置类型定义" -m "- 更新看板娘配置项" -m "- 修改看板娘展示组件逻辑" -m "- 启用看板娘功能"
git push origin master

踩坑复盘

折腾了几天，新的看板娘终于完美地站在了我的博客角落。本以为就是“换个看板娘”这么简单，结果却耗在寻找更合适的看板娘、调试代码、以及反复踩坑上。为了跳出这些坑，我不得不学着使用各种新工具、理解一堆陌生概念，在尝试、失败、再尝试的循环里打转了好一阵子。

踩坑过程

问题	推测原因	行动
加载骨骼数据文件失败	使用的运行时库版本与导出该模型的编辑器版本不兼容	查找对应版本的运行时库
找不到稳定 CDN	官方未提供旧版运行时库的 CDN	下载文件到本地，之后跟着部署到 GitHub Pages
仍然打不开骨骼数据文件	调用 API 时传入的字段名称不正确	根据正确版本的 API 定义填入正确的字段名
成功打开骨骼数据文件，但脸部显示异常	---	尝试禁用预乘 Alpha
背景色全黑	---	开启透明通道并设置背景色
发色出现异常	---	重新启用预乘 Alpha
脸部显示仍然异常	导出资源时未启用预乘 Alpha	下载 Spine 编辑器
Spine Trail 打不开骨骼数据文件	Spine 编辑器版本不合适	改用其他版本的编辑器
导入骨骼数据文件至编辑器，图片显示不正常	缺少图片资源	用纹理解包器解包，之后指定解包后的图片路径
Spine Web Player 打开刚导出的资源时提示版本不支持	版本不正确	尝试修改 JSON 格式的图集文件中的 spine 字段
看板娘显示成功，但在切换动画时她有轻微的上下位移	视口未固定	测量视口并正确配置 viewport 字段
看板娘显示有锯齿	---	使用 CSS `zoom` 进行缩放
切换动画时，光环重置	在其他动画里光环没有移动	分离出光环浮动动画，借助轨道机制实现动画分层

别看上面写的“推测原因”和“行动”好像很准确，其实这些几乎都已经是整理后的“正确路径”了。当时真正的情况是：面对每个问题，我经常毫无头绪，甚至跑错方向。问了 AI，给的答案也常常不到位；最后只能迷茫地在网上搜来搜去，尝试各种可能根本不靠谱的方法。

踩坑教训

版本兼容性很重要：编辑器、运行时库、数据三者的版本必须严格兼容
警惕 API 的静默变更：不同版本间接口或字段可能存在差异，查阅文档时需锁定对应版本，而非仅参考最新
陌生概念是解题的钥匙：主动理解预乘 Alpha、轨道等核心概念，能从根本上定位问题，而非盲目尝试
领域经验是解题的“直觉库”：在特定领域（如 2D 模型处理）积累的经验，能在遇到新问题时，更快地定位方向、形成假设，少走许多弯路

基于 Firefly 主题的 Astro 博客部署（四）：giscus 评论系统配置

Mon, 24 Nov 2025 00:00:00 GMT

站点经过批量配置更新后，如今已颇具辨识度。尽管整体结构仍保留着 Firefly 主题的影子，但最起码能让访客一眼将它与其他博客区分开来。

目前，访客在站内仅能通过点击链接跳转页面、阅读内容。尚缺少一个公开的交流渠道，让访客与访客、博主与访客之间能够直接对话，引入评论系统势在必行。虽然之前设置过 Email 地址、GitHub 链接等，但这些渠道不够直接，也缺乏公开讨论的氛围。要知道，有时评论的价值甚至超越文章本身，沉淀下来的评论也能为后来的访客提供宝贵的线索与回顾。

选择

回想我最初对博客部署的核心需求：快速开始、无需支付服务器和域名的定期费用、界面风格现代，外观精美、可定制化。这些需求也同样延伸到了对评论系统的考量上，并进一步考虑到第三方登录、数据所有权、浏览量统计等方面。

Firefly 主题内置了四种供选择使用的评论系统：Twikoo、Waline、giscus、Disqus。经过调研，得到下面对比结果：

需求	Twikoo	Waline	giscus	Disqus
快速开始	⭐⭐⭐ 快	⭐⭐⭐ 快	⭐⭐⭐⭐ 很快	⭐⭐⭐⭐⭐ 极快（注册即用）
无需定期费用	⭐⭐⭐ 可完全免费	⭐⭐⭐ 可完全免费	⭐⭐⭐⭐⭐ 完全免费	⭐⭐ 免费版含广告，去广告/高级功能需付费
界面现代美观	⭐⭐⭐ 默认较简洁	⭐⭐⭐⭐ 默认较现代	⭐⭐⭐ 原生 GitHub 风格	⭐⭐ 默认较现代、杂乱，但含广告
可定制化	⭐⭐⭐⭐⭐ 高	⭐⭐⭐⭐⭐ 高	⭐⭐⭐ 有限	⭐⭐ 较低
第三方登录	⭐ 不支持，只需填写昵称和邮箱	⭐⭐⭐⭐ 支持国内外社交账号	⭐⭐ 仅支持 GitHub 登录	⭐⭐⭐⭐ 支持国外社交账号
数据所有权	⭐⭐⭐⭐ 完全自己掌握	⭐⭐⭐⭐ 完全自己掌握	⭐⭐⭐ 自己掌握数据在 GitHub 仓库中，公开透明	⭐⭐ 归属于 Disqus
浏览量统计	⭐⭐⭐ 支持	⭐⭐⭐ 支持	⭐ 不支持	⭐⭐⭐⭐ 提供基础访问分析，但含广告追踪

综上来看，可以给出选择依据了：

不选 Twikoo：如果不想自行部署或者注重身份识别
不选 Waline：如果不想自行部署或者不注重身份识别
不选 GitHub：如果希望完全自己掌控或者需要除 GitHub 以外的第三方登录方式
不选 Disqus：如果希望自己完全掌控或者无法接受页面中嵌入广告

对于刚才提出的需求，这四种评论系统其实都基本满足，但在逐一权衡后，我采用了排除法进行决策：

Disqus：因免费版包含广告，首先排除
Twikoo：希望强制评论者进行身份验证，因此排除
Waline：虽然功能强大，但我对免费数据库的数据持久性和请求延迟存疑。相比之下，没有任何免费平台比 GitHub 更能让我对数据安全放心，因此忍痛割舍

最终，考虑到我已经将博客部署于 GitHub Pages，那就索性地用 giscus 好了。虽然浏览量统计的功能，我还是希望有的，但胜在数据安全与深度集成。若未来迁移到云平台上部署，届时再考虑切换至 Waline。

实操

按照 giscus 主页的说明一步一步地操作，并结合 Firefly 主题代码来修改就好。由于 Firefly 主题已经集成好评论系统，所以使用起来很简单。

原理

简单来说，giscus 利用 GitHub Discussions 作为评价系统的后端，通过 GitHub App 和前端嵌入脚本，在静态网站上实现动态评论功能。

下面是它的工作原理分解：

将 GitHub Discussions 作为评论系统的后端（需要手动在仓库设置里开启）
仓库维护者通过安装 giscus App，授予它能读写指定的公开仓库的 Discussions 的权限
在前端借助 <script> 标签嵌入 giscus 提供的脚本并传入参数，作用是：
- giscus 加载时会使用 GitHub Discussions 搜索 API 根据选定的映射方式（如 URL、pathname、<title> 等）来查找与当前页面关联的 discussion。如果找不到匹配的 discussion，giscus 就会在第一次有人留下评论或回应时自动创建一个 discussion
- 动态加载评论界面
- 向 giscus 服务发起请求，带上当前页面的标识
- 将 discussion 的评论内容渲染到页面上
访客需要 GitHub 账号，按照 OAuth 流程登录，授予 giscus App 代表他发布评论的权限（不过从源码可知，实际是 giscus 前端代表访客发布评论的），因为 GitHub 的写操作 API（如创建评论）必须携带访客 OAuth token

由此可见，这过程依赖第三方服务（giscus.app）。由于它是开源的，所以也可以自建。

步骤

1. 启用 GitHub Discussions

在 <username>.github.io （将 <username> 替换为 GitHub 用户名，下文同理）仓库页面下，点击顶部导航栏的 Settings → 向下滚动页面至 Features 部分 → 勾选 Discussions 选项，开启仓库的 Discussions 功能。

2. 安装 giscus GitHub App

访问 GitHub App - giscus → 点击页面右侧栏的 Install 按钮 → 选择 Only select repositories → 点击 Select repositories 下拉列表 → 选择 <username>.github.io 项 → 点击 Install 按钮 → 输入登录密码，确认权限。

3. 修改配置文件

src/config/commentConfig.ts 文件存放着关于评论系统的配置。先配置启用 giscus 评论系统，然后依次设置 repo、repoId、category、categoryId 字段，其中 category 字段选择 Announcements（只有仓库的维护者和 giscus App 本身可以在“Announcements”分类中创建新的 discussion），其他字段根据代码注释去设置。建议先在 giscus 主页上配置下，再将配置的值填入到代码中。

我将文件内容改为：

import type { CommentConfig } from "../types/config";

export const commentConfig: CommentConfig = {
-  type: 'none', // 当前启用的评论系统类型: none, twikoo, waline, giscus, disqus，默认为none，即不启用评论系统。
+  type: 'giscus', // 当前启用的评论系统类型: none, twikoo, waline, giscus, disqus，默认为none，即不启用评论系统。
  // ...
  //giscus评论系统配置（还未测试）
  giscus: {
-    repo: 'CuteLeaf/Firefly', // 设置 Giscus 评论系统仓库
-    repoId: 'R_kgD2gfdFGd', // 设置 Giscus 评论系统仓库ID
-    category: 'General', // 设置 Giscus 评论系统分类
-    categoryId: 'DIC_kwDOKy9HOc4CegmW', // 设置 Giscus 评论系统分类ID
+    repo: 'xpfxzxc/xpfxzxc.github.io', // 设置 Giscus 评论系统仓库
+    repoId: 'R_kgDOQIvG_Q', // 设置 Giscus 评论系统仓库ID
+    category: 'Announcements', // 设置 Giscus 评论系统分类
+    categoryId: 'DIC_kwDOQIvG_c4Cxnv0', // 设置 Giscus 评论系统分类ID
    mapping: 'title', // 设置 Giscus 评论系统映射方式
    strict: '0', // 设置 Giscus 评论系统严格模式
    reactionsEnabled: '1', // 设置 Giscus 评论系统反应功能
    emitMetadata: '1', // 设置 Giscus 评论系统元数据
    inputPosition: 'top', // 设置 Giscus 评论系统输入位置
    theme: 'light', // 设置 Giscus 评论系统主题
    lang: 'zh-CN', // 设置 Giscus 评论系统语言
    loading: 'lazy', // 设置 Giscus 评论系统加载方式
  },
  // ...
};

提交更改并推送至线上

git add src/config/commentConfig.ts
git commit -m "feat: 启用 giscus 评论系统" -m "- 启用评论功能，类型设置为 giscus" -m "- 配置个人 GitHub 仓库作为评论存储" -m "- 设置分类等交互选项"
git push origin custom

扩展内容：OAuth 2.0

在博客页面下，若想通过使用 API 向 GitHub 提交评论至相应的 discussion，必须携带 GitHub 账号登录凭证或者授权令牌。否则 GitHub 将拒绝该请求，这意味着无法匿名评论 —— 每一条评论都需以某一 GitHub 用户的身份发布。

从访客的角度来看，在第三方博客页面直接输入 GitHub 账号和密码，通常存在安全风险，一般访客会对此有所顾虑。此外，受浏览器同源策略的限制，博客网站无法直接获取到 GitHub 域下的凭证信息，哪怕访客当前已在 GitHub 上保持登录状态。

目的

OAuth 2.0 就是为了解决上述问题而生的！它允许资源所有者（访客）在不分享密码的情况下，允许授权服务器（GitHub）授权一个第三方应用（客户端，giscus App）有限地访问存储在另一个服务（资源服务器，GitHub）上的资源。

[!NOTE] 虽说可以让博客站点成为类似 giscus 这样“第三方应用”的存在，从而不需要 giscus 服务，但是这增加了维护后端的负担。而且，访客是否愿意信任博客站点，这也是一个问题。

OAuth 2.0 里有 4 种授权模式，这里只讲解授权码模式，该模式是最安全、最常用，适用于有后端的 Web 应用。

授权码模式

流程：
1. 用户访问客户端，客户端将用户重定向到授权服务器
2. 用户在授权服务器上登录并同意授权
3. 授权服务器将用户重定向回客户端事先指定的地址（回调地址），并在 URL 中带上一个授权码
4. 客户端的后端服务器用这个授权码，连同自己的客户端 ID 和密钥，向授权服务器请求访问令牌
5. 授权服务器验证通过后，返回访问令牌（和可选的刷新令牌）
优点：访问令牌不会暴露给前端浏览器，非常安全

[!NOTE] 在实际过程中，通信时携带的数据，需查阅相关文档以确定哪些参数是必需或可选的。

例子

在静态博客站点中借助第三方 giscus App 实现在仓库的 Discussions 发布评论，由于静态博客站点本身不具备后端服务且未注册为 GitHub App，同时还需引入第三方 giscus App 作为中介，整个授权和发布流程会因此变得相对复杂。

下面将结合博客站点、giscus App 和 giscus 代码片段具体讲解整个过程，开始前有准备工作。

将 giscus 注册为 GitHub App

（这步 giscus 已经做了）先部署 giscus，然后要在 Register new GitHub App 页面上将 giscus 注册为 GitHub App，并按照要求填入信息：

GitHub App name
Description（可选）
Homepage URL
Callback URL：使用 https://[YOUR-DOMAIN-HERE]/api/oauth/authorized 作为授权回调 URL，例如：https://giscus.app/api/oauth/authorized
Expire user authorization tokens：不勾选，目前 giscus 不支持它
Request user authorization (OAuth) during installation：不勾选
Webhook 部分的 Active：不勾选
Repository permissions：选择 Discussions 的 Access: Read & write

点击 Create GitHub App 按钮后，将 giscus 注册为 GitHub App，以后称呼它为 giscus App。

一旦创建完成，就要点击 Generate a new client secret 和 Generate a private key 按钮分别创建客户端密钥和私钥，其中私钥会自动被下载下来。

上面的 Callback URL、App ID、Client ID、Client secret、Private key 后面都会用到的。

为仓库安装 giscus App

在目标仓库中完成该 GitHub App 的授权安装后，GitHub 会为此次安装分配一个唯一的 installation ID。giscus 服务端后续可凭此 ID 换取一个 installation access token，从而获得以 App 身份在仓库中创建“Announcements”类型 discussion 的权限：

giscus 服务端会用 App 的私钥生成一个 JWT 用于证明“我是这个 GitHub App”
giscus 服务端接着携带该 installation ID 和 JWT，调用 GitHub API 请求安装令牌
经 GitHub 验证 JWT 后，服务端会得到一个 installation access token，这个令牌带有仓库级别的权限（比如 Discussions 的读写）
giscus 服务端缓存它，等到需要的时候再使用

接着，启用该仓库的 Discussions 功能，并在前端页面插入脚本并配置好后，访客就可以正常使用 giscus 评论系统了。

授权和使用流程

第一步：博客站点引导访客至 GitHub 授权端点

当访客在博客文章页面里点击 giscus 界面上的 使用 GitHub 登录 按钮后，浏览器将跳转至 giscus 的授权请求端点。此端点 URL 中已通过 redirect_url 参数指定了回调地址，例如：

https://giscus.app/api/oauth/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A4321%2Fposts%2Fastro-firefly-blog-deploy-part4%2F%23comments

这意味着，授权流程结束后，访客将被带回初始的文章页面（http://localhost:4321/posts/astro-firefly-blog-deploy-part4/#comments）。

giscus App 会处理该请求，根据源码：

import type { NextApiRequest, NextApiResponse } from 'next';
import { encodeState } from '../../../lib/oauth/state';
import { env } from '../../../lib/variables';

const GITHUB_OAUTH_AUTHORIZE_URL = 'https://github.com/login/oauth/authorize';

export default async function OAuthAuthorizeApi(req: NextApiRequest, res: NextApiResponse) {
  const appReturnUrl = req.query.redirect_uri as string;

  if (!appReturnUrl) {
    res.status(400).json({ error: '`redirect_uri` is required.' });
    return;
  }

  const { client_id } = env;
  const proto = req.headers['x-forwarded-proto'] || 'http';
  const redirect_uri = `${proto}://${req.headers.host}/api/oauth/authorized`;
  const state = await encodeState(appReturnUrl, env.encryption_password);

  const oauthParams = new URLSearchParams({ client_id, redirect_uri, state });
  res.redirect(302, `${GITHUB_OAUTH_AUTHORIZE_URL}?${oauthParams}`);
}

giscus 服务端会立即构造一个特殊的 GitHub URL 并将访客的浏览器重定向过去。

例如，URL 和参数：

GET https://github.com/login/oauth/authorize?
  client_id=Iv1.c654bd032df6a55f&
  redirect_uri=https://giscus.app/api/oauth/authorized&
  state=032e2710f1484e164291ddferX/0OIIoT+b4Dsmy6hhD6QimL9cdx4EN2PZdmQGrLBwfCGbC5n6pEL9mJVYEGIiakJc8ZSd34wtSoxebcDhqV2IIryat1TK+D89AK37hQyi/tDvko5swfzlYgnlMZ2qOvNgZeFqM2/Bl64oJkyc+xo0OkVNB6r5vpA==

参数讲解：

client_id：giscus App 的唯一标识符。这个就是在注册为 GitHub App 后得到的 Client ID
redirect_uri：回调地址。这是将 giscus 注册为 GitHub App 时预先填写的 Callback URL。授权成功后，GitHub 会把访客（和授权码）送回这个地址。这是安全的关键，防止授权码被发送到任意地址
state：一个随机的、不可猜测的字符串。从上面 giscus 源码片段可知，它将重定向地址（博客网页地址）进行了加密并作为 state 的值

第二步：访客在 GitHub 上进行认证和授权

访客的浏览器被重定向到 https://github.com/login/oauth/authorize?...
如果访客未登录 GitHub，会看到登录页面，访客需要输入 GitHub 的用户名和密码。<strong>注意：</strong>密码是输给 GitHub 的，博客站点完全看不到
登录成功后，GitHub 会显示一个授权页面，询问访客：“Giscus by Giscus 希望获得以下许可...”，并列出请求的权限
访客点击绿色的 Authorize giscus 按钮

[!NOTE] 还有一些情况是：重定向后，需要从多个账号中选择；或者，之前已经授权过，不需要再授权。但不管怎么样，授权过程类似。

第三步：GitHub 重定向回 giscus App 并携带授权码

访客点击授权后，GitHub 的授权服务器会生成一个短期有效的授权码，然后将访客的浏览器重定向到 giscus App 预先注册的回调地址（与第一步中 giscus 服务端指定的 redirect_uri 参数一致），即 https://giscus.app/api/oauth/authorized。

URL 和参数：

GET https://giscus.app/api/oauth/authorized?
  code=604a74dcc85e661b7a9b&
  state=c036727482c11062ed961334%2FdS8DSACyyCYlAhLeDC1cK1jhxrjUGctAQQDiSm6mdevw1crmOPggFYjkPBH2cpuP5ZhHtuB5VFvmnYPJ3x6Fv%2B9YoynA667JiUnaHx6iaULJtOlH%2Bzodau0S4pVQq19p%2BigTYnhXZ%2BsyaHLhIin0rBX2w%2BeBflD9A%3D%3D

参数讲解：

code：授权码。它是一个代表用户同意的凭证，但本身不能用来访问 API
state：原样返回第一步中传来的 state 参数

第四步：giscus App 用授权码向 GitHub 兑换访问令牌

giscus App 在 /api/oauth/authorized 端点处理回调：

import type { NextApiRequest, NextApiResponse } from 'next';
import { encodeState, decodeState } from '../../../lib/oauth/state';
import { env } from '../../../lib/variables';

const GITHUB_OAUTH_ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
const TOKEN_VALIDITY_PERIOD = 1000 * 60 * 60 * 24 * 365; // 1 year;

export default async function OAuthAuthorizedApi(req: NextApiRequest, res: NextApiResponse) {
  const code = req.query.code as string;
  const state = req.query.state as string;
  const error = req.query.error as string;

  const { client_id, client_secret, encryption_password } = env;

  let appReturnUrl: string;
  try {
    appReturnUrl = await decodeState(state, encryption_password);
  } catch (err) {
    res.status(400).json({ error: err.message });
    return;
  }

  const returnUrl = new URL(appReturnUrl);

  if (error && error === 'access_denied') {
    res.redirect(302, returnUrl.href);
    return;
  }

  if (!code || !state) {
    res.status(400).json({ error: '`code` and `state` are required.' });
    return;
  }

  const init = {
    method: 'POST',
    body: new URLSearchParams({ client_id, client_secret, code, state }),
    headers: {
      Accept: 'application/json',
      'User-Agent': 'giscus',
    },
  };

  let accessToken: string;
  try {
    const response = await fetch(GITHUB_OAUTH_ACCESS_TOKEN_URL, init);
    if (response.ok) {
      const data = await response.json();
      accessToken = data.access_token;
    } else {
      throw new Error(`Access token response had status ${response.status}.`);
    }
  } catch (err) {
    res.status(503).json({ error: err.message });
    return;
  }

  const session = await encodeState(
    accessToken,
    encryption_password,
    Date.now() + TOKEN_VALIDITY_PERIOD,
  );
  returnUrl.searchParams.set('giscus', session);

  res.redirect(302, returnUrl.href);
}

giscus App 会解析和验证 state 参数，然后构造一个服务器对服务器的 POST 请求向 GitHub 请求访问令牌，请求体包含 client_id、client_secret、code 和 state 参数。

第五步：GitHub 返回访问令牌给 giscus App

GitHub 验证 client_secret 和 code 后，返回 JSON 数据。giscus App 从响应中提取出 access_token。

第六步：giscus App 创建加密 Session 并重定向回博客站点

giscus App 没有像传统 Web 应用那样用这个 token 直接为用户创建会话 Cookie，而是将 token 安全地“传回”给博客站点上的 giscus 前端组件。

它将得到的访问令牌加密成一个名为 session 的字符串，并将解密得到的 appReturnUrl（即博客文章页面的地址）在其 URL 参数后附加 ?giscus=<加密的session字符串>，然后向访客的浏览器返回一个 302 重定向指令。

最终重定向 URL，例如：

GET http://localhost:4321/posts/astro-firefly-blog-deploy-part4/?
  giscus=84c57886f2d88be979c1674dQODpjiFTL2GxjTO2QRcnHEHvvyshy%2Bxf5iI6Re5SlXkrbo6o0MkqMMLyr8X8fL3zxlSvW3IFtr5OTbmJ%2FQN%2Fw%2BDmch0KKPwK4bViYUoeI5gtD1P5WNI8d5Xg08s%3D#comments

访客的浏览器此刻被带回了最初的博客文章页面，并且 URL 中携带了一个神秘的 giscus 参数。

第七步：静态博客网页处理 giscus 回调参数

当浏览器被重定向回后，嵌入在页面中的 giscus 客户端脚本（client.ts）开始工作。

检测并存储 Session：

// Set up session and clear the session param on load
const url = new URL(location.href);
let session = url.searchParams.get('giscus') || '';
const savedSession = localStorage.getItem(GISCUS_SESSION_KEY);
url.searchParams.delete('giscus');
url.hash = '';
const cleanedLocation = url.toString();

if (session) {
  localStorage.setItem(GISCUS_SESSION_KEY, JSON.stringify(session));
  history.replaceState(undefined, document.title, cleanedLocation);
} else if (savedSession) {
  try {
    session = JSON.parse(savedSession);
  } catch (e) {
    localStorage.removeItem(GISCUS_SESSION_KEY);
    console.warn(`${formatError(e?.message)} Session has been cleared.`);
  }
}

加密的 session 字符串被安全地存储在浏览器 localStorage 中，URL 被清理干净。此时，前端持有了代表用户授权状态的凭证（加密的 session），但还无法直接使用它。

第八步：giscus Widget Iframe 加载并传递 Session

giscus 客户端脚本开始构造并加载评论组件的 Iframe。

构造 widget 参数

const attributes = script.dataset;
const params: Record<string, string> = {};

params.origin = cleanedLocation;
params.session = session as string;
params.theme = attributes.theme as string;
params.reactionsEnabled = attributes.reactionsEnabled || '1';
params.emitMetadata = attributes.emitMetadata || '0';
params.inputPosition = attributes.inputPosition || 'bottom';
params.repo = attributes.repo as string;
params.repoId = attributes.repoId as string;
params.category = attributes.category || '';
params.categoryId = attributes.categoryId as string;
params.strict = attributes.strict || '0';
params.description = getMetaContent('description', true);
params.backLink = getMetaContent('giscus:backlink') || cleanedLocation;

switch (attributes.mapping) {
  case 'url':
    params.term = cleanedLocation;
    break;
  case 'title':
    params.term = document.title;
    break;
  case 'og:title':
    params.term = getMetaContent('title', true);
    break;
  case 'specific':
    params.term = attributes.term as string;
    break;
  case 'number':
    params.number = attributes.term as string;
    break;
  case 'pathname':
  default:
    params.term =
      location.pathname.length < 2
        ? 'index'
        : location.pathname.substring(1).replace(/\.\w+$/, '');
    break;
}

// Check anchor of the existing container and append it to origin URL
const existingContainer = document.querySelector('.giscus');
const id = existingContainer && existingContainer.id;
if (id) {
  params.origin = `${cleanedLocation}#${id}`;
}

// Set up iframe src and loading attribute
const locale = attributes.lang ? `/${attributes.lang}` : '';
const src = `${giscusOrigin}${locale}/widget?${new URLSearchParams(params)}`;
const loading = attributes.loading === 'lazy' ? 'lazy' : undefined;

最终生成的 Iframe URL：

https://giscus.app/zh-CN/widget?
  origin=http://localhost:4321/posts/astro-firefly-blog-deploy-part4/#comments&session=9217fcd7459b93e3e27c1e25V7QDChvHmxQVKInMCD9q7LmScNiJfdGOBFZalw4jOEKaUeEPkQV2pgryenES7rtkfn4u3n9deNbmgvgCPXpMb4n5QsySzFbOGounl/MNrSEd6gTuX5nGeK8j0Vw=&
  repo=xpfxzxc/xpfxzxc.github.io&
  repoId=R_kgDOQIvG_Q&
  category=Announcements&
  categoryId=DIC_kwDOQIvG_c4Cxnv0&
  term=基于 Firefly 主题的 Astro 博客部署（四）：giscus 评论系统配置 - 未来之蓝 | xpfxzxc 的个人博客&
  number=&
  strict=0&
  reactionsEnabled=1&
  emitMetadata=1&
  inputPosition=top&
  theme=light&
  description=记录了自己在基于 Firefly 主题的 Astro 博客上配置启用 giscus 评论系统，并简单总结了该评论系统的部分流程。&
  backLink=http://localhost:4321/posts/astro-firefly-blog-deploy-part4/

创建并加载 Iframe：

// Set up iframe element
const iframeElement = document.createElement('iframe');
const iframeAttributes = {
  class: 'giscus-frame giscus-frame--loading',
  title: 'Comments',
  scrolling: 'no',
  allow: 'clipboard-write',
  src,
  loading,
};
Object.entries(iframeAttributes).forEach(
  ([key, value]) => value && iframeElement.setAttribute(key, value),
);

iframe 开始加载，向 giscus.app/widget 发起请求，并带上了所有配置参数和加密的 session。

第九步：giscus Widget 服务端解密 Session 获取 Token

当 iframe 加载 https://giscus.app/widget?... 时，由 Next.js 的 getServerSideProps 服务端处理。

服务端接收参数：

const session = (query.session as string) || '';
const repo = (query.repo as string) || '';
// ... 接收其他参数

解密 Session 获取 Access Token：

const { encryption_password } = env;
const token = await decodeState(session, encryption_password)
  .catch(() => getAppAccessToken(repo))
  .catch(() => '');

服务端渲染 Widget：

使用获取到的 token，服务端可以调用 GitHub API 获取评论数据、用户信息等
将数据作为 props 传递给 React 组件，渲染出包含评论列表和评论框的完整 UI
服务端会设置重要的 CSP 头，确保 iframe 只能被授权的站点嵌入

第十步：前端 Token 的安全使用与消息通信

Token 不暴露给父页面

解密出的真实 Access Token 仅存在于 giscus App 和它返回的 Widget 页面上下文中。Token 永远不会发送回博客站点的父页面脚本，从而避免了潜在的前端安全风险。

基于 postMessage 的通信

当访客在 Iframe 的评论框中发表评论时，<u>iframe 内部的 giscus 代码会直接使用它拥有的 Token 去调用 GitHub API*</u>。

iframe 与父页面之间通过 postMessage 进行安全的跨域通信，仅传递 UI 状态，绝不传递 Access Token。

// Listen to messages
window.addEventListener('message', (event) => {
  if (event.origin !== giscusOrigin) return;

  const { data } = event;
  if (!(typeof data === 'object' && data.giscus)) return;

  if (data.giscus.resizeHeight) {
    iframeElement.style.height = `${data.giscus.resizeHeight}px`;
  }

  if (data.giscus.signOut) {
    localStorage.removeItem(GISCUS_SESSION_KEY);
    console.log(`[giscus] User has logged out. Session has been cleared.`);
    signOut();
    return;
  }
  // ...
})

第十一步：用户状态维持与登出

只要 localStorage 中的加密 session 不被清除，访客下次访问博客站点时，giscus 客户端会自动从 localStorage 读取 session 并传递给 Widget，让访客保持登录状态。

当在 Widget 中点击登出时，iframe 会通过 postMessage 发送一个 signOut 指令。博客文章页面的 giscus 客户端收到后，会重置 iframe 的 src（不带 session），强制重新加载为未登录状态，同时清理本地存储：

function signOut() {
  delete params.session;
  const src = `${giscusOrigin}${locale}/widget?${new URLSearchParams(params)}`;
  iframeElement.src = src; // Force reload
}

基于 Firefly 主题的 Astro 博客部署（三）：站点配置修改

Wed, 19 Nov 2025 00:00:00 GMT

在成功地在 GitHub Pages 上部署了博客，并紧接着在博客上发布文章后，看着自己撰写的文章被编排、美化成好看的页面显示在博客网站上，我的内心里瞬间有了以后在博客上撰写文章的动力。

目前，我的博客网站上包括个人名称、头像、介绍、公告、背景壁纸等在内的各种信息，仍是原 Firefly 主题作者预设的默认内容。我计划接下来逐步替换这些信息。毕竟，GitHub Pages 上的内容能够被搜索引擎收录的，作为博主，我当然不希望自己写的文章被他人阅读时，被误认为是他人所写；同时，也不希望博客中的其他信息与其他人雷同。

src/config 目录下存放着博客的相关配置文件：

src/
├── config/
│   ├── index.ts              # 配置索引文件
│   ├── siteConfig.ts         # 站点基础配置
│   ├── profileConfig.ts      # 用户资料配置
│   ├── commentConfig.ts      # 评论系统配置
│   ├── announcementConfig.ts # 公告配置
│   ├── licenseConfig.ts      # 许可证配置
│   ├── footerConfig.ts       # 页脚配置
│   ├── FooterConfig.html     # 页脚HTML内容
│   ├── expressiveCodeConfig.ts # 代码高亮配置
│   ├── sakuraConfig.ts       # 樱花特效配置
│   ├── fontConfig.ts         # 字体配置
│   ├── sidebarConfig.ts      # 侧边栏布局配置
│   ├── navBarConfig.ts       # 导航栏配置
│   ├── musicConfig.ts        # 音乐播放器配置
│   ├── pioConfig.ts          # 看板娘配置
│   ├── adConfig.ts           # 广告配置
│   ├── friendsConfig.ts      # 友链配置
│   └── sponsorConfig.ts      # 赞助配置

元数据配置

站点元数据配置，主要包括标题、描述、关键词和 Favicon。这些配置信息对于 SEO 至关重要，通常会被注入到网站的 HTML 头部（<head> 区域），供浏览器和搜索引擎读取。

siteConfig.ts 文件里存放着这些配置信息。

关于 title 和 subtitle 字段，最终会被如何使用，src/layouts/Layout.astro 文件里有相关代码段：

let pageTitle: string;
if (title) {
	pageTitle = `${title} - ${siteConfig.title}`;
} else {
	pageTitle = siteConfig.subtitle
		? `${siteConfig.title} - ${siteConfig.subtitle}`
		: siteConfig.title;
}

这段代码根据是否传入 title 参数来决定页面标题的格式，这样可以确保：

文章页面显示：文章标题 - <title>
首页显示：<title> - <subtitle>
其他页面根据传入的 title prop 显示对应标题

为了有利于 SEO，对于标题、描述和关键词，我将 siteConfig.ts 文件内容修改为：

export const siteConfig: SiteConfig = {
-  title: "Firefly",
-  subtitle: "Demo site",
-  description:
-    "Firefly 是一款基于 Astro 框架开发的清新美观且现代化个人博客主题，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。",
+  title: "未来之蓝 | xpfxzxc 的个人博客",
+  subtitle: "个人学习和日常零散想法的记录空间，内容随性且不定期更新",
+  description: "未来之蓝是 xpfxzxc 的个人博客，记录个人学习和日常零散想法。心怀蔚蓝愿景，脚踏实地前行。每一篇记录都是通向理想未来的坚实脚印。",
  keywords: [
-    "Firefly",
-    "Fuwari",
-    "Astro",
-    "ACGN",
-    "博客",
-    "技术博客",
-    "静态博客",
+    "xpfxzxc", "未来之蓝", "个人博客",
+    "个人成长", "技术分享", "生活随想",
+    "编程学习", "ACGN", "动漫", "二次元", "游戏",
+    "非专业博客", "学习记录", "读书笔记"
  ],

Favicon 是 favorites icon 的缩写，也被称为网页图标，它是与网站相关联的图标，通常显示在浏览器的地址栏、书签栏或标签页上。通常而言，Favicon 与网站 Logo 在设计上是相同的，仅尺寸不同。它也可能是 Logo 中的首字或首字母，或是某个标志性图案的提炼。

我打算先完成 Logo 的设计（具体步骤后述），随后使用 ImageMagick 将其转换为 ICO 格式（.ico），目标尺寸为 32×32 像素（假设 Logo 原始尺寸已为 1:1 比例）:

magick logo.png -resize 32x32 favicon.ico

替换了 Favicon 后，维持 siteConfig.ts 文件内相关配置代码段不动：

// ...
favicon: [
  // 留空以使用默认 favicon
  {
    src: "/assets/images/favicon.ico", // 图标文件路径
    theme: "light", // 可选，指定主题 'light' | 'dark'
    sizes: "32x32", // 可选，图标大小
  },
],
// ...

如果将 favicon 字段设置为空数组，将使用 public/favicon 目录里的图标。

站点 Logo 和名称

站点 Logo 和名称位于顶部导航栏的左部分。其配置不在 navBarConfig.ts 文件中，而在 siteConfig.ts 文件中的一部分。

Logo 与相对通用的头像或背景壁纸不同，它需要具备独特的辨识度，以避免与其他站点雷同，从而体现博客的个性。因此，若懂设计，强烈推荐亲自设计。若不懂，也有以下解决方案：

AI 智能生成（抽卡）：
- Canva：全球最流行的在线设计工具
- NovelAI：专注于二次元图像生成和故事创作
- Stable Diffusion：免费、开源、控制力强，拥有大量各种的模型，可本地部署或使用在线平台
- Midjourney：收费、闭源，艺术感和质感之王
- LibibAI：国内领先的 AI 创作平台，提供了原汁原味的 webUI、comfyUI 等在线 AI 绘图工具免费试用，可在线进行模型训练、使用各种模型
打造纯文字 Logo：挑选一款特色字体，文字使用中英文组合，进行细节修饰、微调
交给专业人士：
- 淘宝/咸鱼：搜索“Logo设计”，有许多工作室接单，价格非常亲民
- 专业设计平台：特赞、站酷
- 社交媒体：在微博、小红书等平台上找独立设计师约稿

Firefly 主题风格简洁美观，并且与二次元元素非常契合，这从主题演示站点的出色效果可见一斑。这让我决定采用二次元风格的头像和背景壁纸。自然地，与之配套的 Logo 和 Favicon 也应选择统一的二次元风格。

我打算先在 NovelAI 平台上输入 Prompt 来进行“抽卡”，看能不能抽出看得过去的 Logo。NovelAI 平台的新账号拥有 30 张图片的免费生成额度。

我通过 AI 来辅助生成 Prompt：首先，我将网站的标题、副标题、描述、关键词，还有之后要使用的头像和背景壁纸的相关信息输入到 AI；然后，将其生成的多个 Prompt 逐一复制到 NovelAI 里的 Prompt 输入框里，并执行图片生成。在生成图片之前，可以设置其尺寸大小，例如：1:1 比例的 1024×1024 尺寸。根据生成的情况，可能要尝试好几种 Prompt，也可能需对同一个 Prompt 多次执行图片生成。最后，从生成的多张图片中挑选出几张看得过去的图片。

我最终使用的 Logo，是根据以下 Prompt 生成的：

masterpiece, minimalist logo, an open book from which emerges a constellation of three stars flying upwards, symbolizing ideas reaching for the future. Solid color design in hue 230, white background, clean vector graphic, no gradient --niji 6 --style raw

使用该 Prompt 生成的图片通常为白底。若直接用作 Logo，视觉效果不佳，因此下一步需移除背景，将其变为透明。可以选用 removebg 等在线工具或其他软件来移除背景。

目前得到的 Logo 图片格式是 PNG。作为优化流程的一环，Logo 应被转换为 WEBP 这类现代图片格式：

magick logo.png -quality 85 logo.webp

给博客站点取了个名称后，我将 siteConfig.ts 文件内容修改为：

// ...
// 导航栏Logo
// navbarLogo 支持三种类型：Astro图标库，本地图片，网络图片
// { type: "icon", value: "material-symbols:home-pin-outline" }
// { type: "image", value: "/assets/images/logo.webp", alt: "Firefly Logo" }
// { type: "image", value: "https://example.com/logo.png", alt: "Firefly Logo" }
navbarLogo: {
  type: "image",
-    value: "/assets/images/LiuYingPure3.svg",
+    value: "/assets/images/logo.webp",
-    alt: "🍀",
+    alt: "未来之蓝博客 Logo - 一本翻开的书与飞向上方的星辰，象征知识、记录与通向未来的愿景",
  },
-  navbarTitle: "Firefly", // 导航栏标题，可以设置为与 title 不同的值，如果不设置则使用 title
+  navbarTitle: "未来之蓝", // 导航栏标题，可以设置为与 title 不同的值，如果不设置则使用 title
}
// ...

个人基本资料

个人基本资料位于页面的左侧栏。profileConfig.ts 文件里存放着个人资料配置，例如修改个人头像、名称、介绍和社交栏设置。

个人头像的获取渠道很多，选取时需与网站主题风格保持一致。个人名称可直接使用自己熟悉的网名。个人介绍若无灵感，可先参考其他博主的写法。在社交栏处，可以登记下自己常用的社交媒体链接。

对于像头像这样较大或更大的图片，最好使用 WebP 格式，WebP 的优势如下：

在同等视觉质量下，惊人的体积压缩
更快的页面加载速度
支持无损或有损压缩、透明度

使用 ImageMagick 将 PNG 或 JPG 批量或单个转换为 WebP 格式很简单，例如：

# 有损压缩，质量 85（常用）
magick avatar.png -quality 85 avatar.webp

替换了头像图片之后，我将 profileConfig.ts 文件内容修改为：

import type { ProfileConfig } from "../types/config";

export const profileConfig: ProfileConfig = {
  avatar: "/assets/images/avatar.webp",
-  name: "Firefly",
-  bio: "Hello, I'm Firefly.",
+  name: "xpfxzxc",
+  bio: "不愿沉溺于无力感，正试着将碎片化的思考转化成可见的成长足迹。",
  links: [
    {
-      name: "Bilibli",
-      icon: "fa6-brands:bilibili",
-      url: "https://space.bilibili.com/38932988",
+      name: "Email",
+      icon: "material-symbols:mail",
+      url: "mailto:xpfxzxc@gmail.com",
    },
    {
      name: "GitHub",
      icon: "fa6-brands:github",
-      url: "https://github.com/CuteLeaf",
+      url: "https://github.com/xpfxzxc",
+    },
+    {
+      name: "Bilibli",
+      icon: "fa6-brands:bilibili",
+      url: "https://space.bilibili.com/12533717",
+    },
+    {
+      name: "Steam",
+      icon: "fa6-brands:steam",
+      url: "https://steamcommunity.com/profiles/76561198327614842",
    },
  ],
};

关于 icon 字段，在网络上搜索 fa6-brands online，即可查询到相关的图标搜索网站：

站点公告

公告同样位于页面的左侧栏。announcementConfig.ts 文件里存放着公告配置，但卡片上的 公告 字样可以自定义为其他标题，因此严格来说该区域的内容不一定是“公告”？

我将文件内容修改为：

import type { AnnouncementConfig } from "../types/config";

export const announcementConfig: AnnouncementConfig = {
-  title: "公告", // 公告标题
-  content: "欢迎来到我的博客！这是一则示例公告。", // 公告内容
-  closable: true, // 允许用户关闭公告
+  title: "站点说明", // 公告标题
+  content: "个人学习和日常零散想法的记录空间，内容随性且不定期更新。", // 公告内容
+  closable: false, // 禁止用户关闭公告
  link: {
-    enable: true, // 启用链接
+    enable: false, // 关闭链接
    text: "了解更多", // 链接文本
    url: "/about/", // 链接 URL
    external: false, // 内部链接
  },
};

导航栏

导航栏位于页面的顶部中间部分。navBarConfig.ts 文件里存放着导航栏配置，它是一个链接对象数组。每个链接对象，要么是 LinkPreset 链接预设枚举，要么是自定义链接对象。当自定义链接对象时，使用 children 字段可以生成多级菜单。

我将文件内容修改为：

import type { NavBarConfig, NavBarLink } from "../types/config";
import { LinkPreset } from "../types/config";
import { siteConfig } from "./siteConfig";

// 根据页面开关动态生成导航栏配置
const getDynamicNavBarConfig = (): NavBarConfig => {
  const links: (NavBarLink | LinkPreset)[] = [
    LinkPreset.Home,
    LinkPreset.Archive,
  ];

  // 支持自定义导航栏链接,并且支持多级菜单
  links.push({
    name: "链接",
    url: "/links/",
    icon: "material-symbols:link",
    children: [
+      {
+        name: "Email",
+        url: "mailto:xpfxzxc@gmail.com",
+        external: true,
+        icon: "material-symbols:mail",
+      },
      {
        name: "GitHub",
-        url: "https://github.com/CuteLeaf/Firefly",
+        url: "https://github.com/xpfxzxc",
        external: true,
        icon: "fa6-brands:github",
      },
      {
        name: "Bilibili",
-        url: "https://space.bilibili.com/38932988",
+        url: "https://space.bilibili.com/12533717",
        external: true,
        icon: "fa6-brands:bilibili",
      },
+      {
+        name: "Steam",
+        url: "https://steamcommunity.com/profiles/76561198327614842",
+        external: true,
+        icon: "fa6-brands:steam",
+      },
    ],
  });

  links.push(LinkPreset.Friends);

  // 根据配置决定是否添加留言板页面
  if (siteConfig.pages.guestbook) {
    links.push(LinkPreset.Guestbook);
  }

  links.push({
    name: "关于",
    url: "/content/",
    icon: "material-symbols:info",
    children: [
      ...(siteConfig.pages.anime ? [LinkPreset.Anime] : []), // 根据配置决定是否添加追番页面
      ...(siteConfig.pages.sponsor ? [LinkPreset.Sponsor] : []), // 根据配置决定是否添加赞助页面
      LinkPreset.About,
    ],
  });
  return { links };
};

export const navBarConfig: NavBarConfig = getDynamicNavBarConfig();

关于 icon 字段里用到的 Material Symbols，更多图标可在 Material Symbols and Icons 网站中搜索。

背景壁纸

虽然 Unsplash、Pexels、Pixabay 等网站提供海量高质量图片，但是我不喜欢这些网站上的图片风格，比如：自然、生活、简约、插画、抽象、纹理、摄影、渐变、写实等。我认为这些图片倒是比较适合作为商业册子上的图案或者电子设备上的背景壁纸。其中，大部分图片看着令我感到压抑感；小部分图片单独看着还可以，但作为网页背景壁纸时不太适配 Firefly 主题现有元素风格。与其用这些背景壁纸，不如采用极简风格的色彩搭配或直接使用纯色背景。

既然我之前选用的头像是二次元风格，而且 Firefly 主题演示站点用的背景壁纸看起来美观，令人感到舒适，那就使用 Pixiv 或 zerochan 等网站上高质量插画来作为博客的背景壁纸。在选择的过程中，要注意避免版权问题，最好选择作者明确标明“可自由使用” 或 CC0、CC BY 授权的插画。

此外，在网友自建的壁纸站里找高质量壁纸也是一种很好的选择。比如：恋风画廊 - 高质量壁纸下载。

针对不同设备的屏幕比例特性，一般来说：移动端优先采用竖屏背景壁纸，而非移动端（如 PC、平板）则统一采用横屏背景壁纸。

为了优化浏览体验，建议将选定的背景壁纸转换为 WEBP 格式。可以替换掉 public/assets/images 目录下的 d1.webp（桌面端）和 m1.webp（移动端）文件，也可另取文件名保存。注意，将背景壁纸本地化保存可有效避免因外部链接失效导致的显示问题。

背景壁纸相关的配置在 siteConfig.ts 文件里 backgroundWallpaper 字段上，里面有非常多的选项可以配置。几乎所有的选项都已有注释，非常好理解，不过，position 选项的理解需要额外学习一些 CSS 知识点。

// ...
// 图片位置
// 支持所有CSS object-position值，如: 'top', 'center', 'bottom', 'left top', 'right bottom', '25% 75%', '10px 20px'..
// 如果不知道怎么配置百分百之类的配置，推荐直接使用：'center'居中，'top'顶部居中，'bottom' 底部居中，'left'左侧居中，'right'右侧居中
position: "0% 20%",
// ...

根据代码注释和源码，这里 position 选项的值会直接运用到 CSS 的 object-position 属性上。object-position 属性的作用：想象成照片（可替换元素）在相框（内容框）里移动，具体来说，照片上的哪个点与相框上的哪个点对齐。

CSS object-fit 通常配合 object-position 属性使用，它的值：

cover：照片按其宽高比进行缩放，直至完全覆盖相框，可能会裁剪一部分
contain：照片按其宽高比进行缩放，直到完整显示在相框内，可能会留有空白
fill（默认）：照片会被拉伸或压缩，以填满整个相框，可能会变形

在源码中，已经将 object-fit 属性的值设置成 cover 了。

综上来看，配置文件中的 position: 0 20% 的含义是：保持相框不动，让图片在垂直方向上向上移动，从而在容器中展示出图片更靠下的区域，就等于告诉浏览器：“不想看这张大图最顶上的一部分，请把画面往下挪一点再给我看。”这表明如果使用这个值的话，使用的背景壁纸顶部将被裁剪掉的一小部分不要有“太重要”的内容。

在“横幅壁纸”模式下，主页横幅区域设有标题与副标题文字，其中副标题会从预设的若干组文字中动态轮换，并呈现逐字键入与删除的动态效果。文字内容需要兼顾节奏与韵律、意境与画面、情感共鸣、系列感与统一。

在该模式下，当前可能存在两个显示协调性问题：

在主页面中，横幅的主标题和副标题可能会遮挡背景壁纸的关键部分（如角色脸部），影像画面整体协调，此时可能需要调整配置文件中的 position 字段。
其他页面的背景壁纸位置相较于主页会略微上移，下方卡片区域也向上移动，导致背景壁纸被遮挡的区域更大，画面看起来不协调。因此，同样可能需要通过调整 position 字段进行修正。

不过，即使调整好了 position 字段，在其他视口尺寸的情况下，同样可能出现遮挡问题。要彻底规避遮挡问题，要么投入更多开发量引入响应式定位机制，要么改用“全屏壁纸”或“纯色背景”模式，甚至直接更换背景壁纸。

最终，我将背景壁纸相关配置改为：

  backgroundWallpaper: {
    // 壁纸模式："banner" 横幅壁纸，"overlay" 全屏壁纸，"none" 纯色背景无壁纸
    mode: "banner",
    // 是否允许用户通过导航栏切换壁纸模式，设为false可提升性能（只渲染当前模式）
    switchable: true,

    // 背景图片配置
    src: {
      // 桌面背景图片
      desktop: "/assets/images/d1.webp",
      // 移动背景图片
      mobile: "/assets/images/m1.webp",
    },

    // Banner模式特有配置
    banner: {
      // 图片位置
      // 支持所有CSS object-position值，如: 'top', 'center', 'bottom', 'left top', 'right bottom', '25% 75%', '10px 20px'..
      // 如果不知道怎么配置百分百之类的配置，推荐直接使用：'center'居中，'top'顶部居中，'bottom' 底部居中，'left'左侧居中，'right'右侧居中
-     position: "0% 20%",
+     position: "center 9%",
      
      homeText: {
        // 主页显示自定义文本（全局开关）
        enable: true,
        // 主页横幅主标题
-       title: "Lovely firefly!",
+       title: "Future Archives!",
        // 主页横幅副标题
        subtitle: [
-         "In Reddened Chrysalis, I Once Rest",
-         "From Shattered Sky, I Free Fall",
-         "Amidst Silenced Stars, I Deep Sleep",
-         "Upon Lighted Fyrefly, I Soon Gaze",
-         "From Undreamt Night, I Thence Shine",
-         "In Finalized Morrow, I Full Bloom",
+         "In Reddened Chrysalis, I Once Rest",
+         "From Shattered Sky, I Free Fall",
+         "Amidst Silenced Stars, I Deep Sleep",
+         "Upon Lighted Fyrefly, I Soon Gaze",
+         "From Undreamt Night, I Thence Shine",
+         "In Finalized Morrow, I Full Bloom",
        ],
        typewriter: {
          enable: true, // 启用副标题打字机效果
          speed: 100, // 打字速度（毫秒）
          deleteSpeed: 50, // 删除速度（毫秒）
          pauseTime: 2000, // 完全显示后的暂停时间（毫秒）
        },
      },
      credit: {
        enable: {
          desktop: true, // 桌面端显示横幅图片来源文本
-         mobile: false, // 移动端显示横幅图片来源文本
+         mobile: true, // 移动端显示横幅图片来源文本
        },
        text: {
-         desktop: "Pixiv - 晚晚喵", // 桌面端要显示的来源文本
-         mobile: "Mobile Credit", // 移动端要显示的来源文本
+         desktop: "Pixiv - 鈴木シロリ", // 桌面端要显示的来源文本
+         mobile: "Pixiv - Orivayne", // 移动端要显示的来源文本
        },
        url: {
-         desktop: "https://www.pixiv.net/artworks/135490046", // 桌面端原始艺术品或艺术家页面的 URL 链接
-         mobile: "", // 移动端原始艺术品或艺术家页面的 URL 链接
+         desktop: "https://www.pixiv.net/artworks/108043909", // 桌面端原始艺术品或艺术家页面的 URL 链接
+         mobile: "https://www.pixiv.net/artworks/130379063", // 移动端原始艺术品或艺术家页面的 URL 链接
        },
      },
      navbar: {
        transparentMode: "semifull", // 导航栏透明模式："semi" 半透明加圆角，"full" 完全透明，"semifull" 动态透明
      },
      // 波浪动画效果配置，开启可能会影响页面性能，请根据实际情况开启
      waves: {
        enable: {
          desktop: true, // 桌面端启用波浪动画效果
          mobile: true, // 移动端启用波浪动画效果
        },
        performance: {
          quality: "high",
          hardwareAcceleration: true, // 是否启用硬件加速
        },
        // 性能优化说明：
        // quality: "high" - 最佳视觉效果，但GPU占用较高，适合高性能设备
        // quality: "medium" - 平衡性能和质量，适合中等性能设备
        // quality: "low" - 最低GPU占用，动画更简单，适合低性能设备
        // hardwareAcceleration: true - 启用GPU加速，提升性能但增加GPU占用
        // hardwareAcceleration: false - 禁用GPU加速，降低GPU占用但可能影响性能
      },
    },

    // 全屏透明覆盖模式特有配置
    overlay: {
      zIndex: -1, // 层级，确保壁纸在背景层
      opacity: 0.8, // 壁纸透明度
-     blur: 1, // 背景模糊程度
+     blur: 0.5, // 背景模糊程度
    },
  },

主题色

更换好 Logo、Favicon、头像图片和背景壁纸后，下一步是选择合适的主题色，以确保网站各元素的色彩整体和谐统一。

当前的主题色系统基于 OKLCH 色彩空间构建。无论是通过配置文件还是界面调节器修改主题色，最终都会作用于 CSS 变量 --hue。系统中主题相关的颜色，都是基于固定的亮度（Lightness）与色度（Chroma）值，结合可变的色相（Hue）值动态计算得出的。例如：

/* ===== 主题相关变量 ===== */
:root {
  --primary: oklch(0.70 0.14 var(--hue));
  --page-bg: oklch(0.95 0.01 var(--hue));
  --card-bg: white;
  --card-bg-transparent: rgba(255, 255, 255, 0.8);
  
  --btn-content: oklch(0.55 0.12 var(--hue));
  --btn-regular-bg: oklch(0.95 0.025 var(--hue));
  --btn-regular-bg-hover: oklch(0.9 0.05 var(--hue));
  --btn-regular-bg-active: oklch(0.85 0.08 var(--hue));
  /* ... */
}
/* ... */

因此，主题色可选的范围非常有限。

我将 siteConfig.ts 文件里的主题色配置为：

themeColor: {
-  hue: 165, // 主题色的默认色相，范围从 0 到 360。例如：红色：0，青色：200，蓝绿色：250，粉色：345
-  fixed: false, // 对访问者隐藏主题色选择器
+  hue: 230, // 主题色的默认色相，范围从 0 到 360。例如：红色：0，青色：200，蓝绿色：250，粉色：345
+  fixed: true, // 对访问者隐藏主题色选择器
  defaultMode: "system", // 默认模式："light" 亮色，"dark" 暗色，"system" 跟随系统
},

字体

基于目前的默认字体配置，虽说字体在我的电脑上显示得很美观，但是在其他电脑上就可能显示得不一样。对此，我有个需求：不管在什么设备上打开博客站点，页面上都要使用同样的字体。

由于我不太了解字体方面，所以在配置前查阅了相关资料，并阅读了一些源码。

字体的相关配置在 fontConfig.ts 文件里：

// 字体配置
export const fontConfig = {
  enable: true, // 启用自定义字体功能
  preload: true, // 预加载字体文件以提高性能
  selected: ["system"], // 当前选择的字体，支持多个字体组合
  fonts: {
    // 系统字体
    system: {
      id: "system",
      name: "系统字体",
      src: "", // 系统字体无需 src
      family:
        "system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
    },
    // Google Fonts - Zen Maru Gothic
    "zen-maru-gothic": {
      id: "zen-maru-gothic",
      name: "Zen Maru Gothic",
      src: "https://fonts.googleapis.com/css2?family=Zen+Maru+Gothic:wght@300;400;500;700;900&display=swap",
      family: "Zen Maru Gothic",
      display: "swap" as const,
    },
    // Google Fonts - Inter
    inter: {
      id: "inter",
      name: "Inter",
      src: "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap",
      family: "Inter",
      display: "swap" as const,
    },
    // 小米字体 - MiSans Normal
    "misans-normal": {
      id: "misans-normal",
      name: "MiSans Normal",
      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Normal.min.css",
      family: "MiSans",
      weight: 400,
      display: "swap" as const,
    },
    // 小米字体 - MiSans Semibold
    "misans-semibold": {
      id: "misans-semibold",
      name: "MiSans Semibold",
      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Semibold.min.css",
      family: "MiSans",
      weight: 600,
      display: "swap" as const,
    },
  },
  fallback: [
    "system-ui",
    "-apple-system",
    "BlinkMacSystemFont",
    "Segoe UI",
    "Roboto",
    "sans-serif",
  ], // 全局字体回退
};

从配置中可知，有两个结构需要去研究一下。

字体选择配置：

// 字体配置
export type FontConfig = {
  enable: boolean; // 是否启用自定义字体功能
  selected: string | string[]; // 当前选择的字体ID，支持单个或多个字体组合
  fonts: Record<string, FontItem>; // 字体库，以ID为键的对象
  fallback?: string[]; // 全局字体回退列表
  preload?: boolean; // 是否预加载字体文件以提高性能
};

单个字体项配置：

// 单个字体配置
export type FontItem = {
  id: string; // 字体唯一标识符
  name: string; // 字体显示名称
  src: string; // 字体文件路径或URL链接
  family: string; // CSS font-family 名称
  weight?: string | number; // 字体粗细，如 "normal", "bold", 400, 700 等
  style?: "normal" | "italic" | "oblique"; // 字体样式
  display?: "auto" | "block" | "swap" | "fallback" | "optional"; // font-display 属性
  unicodeRange?: string; // Unicode 范围，用于字体子集化
  format?:
    | "woff"
    | "woff2"
    | "truetype"
    | "opentype"
    | "embedded-opentype"
    | "svg"; // 字体格式，仅当 src 为本地文件时需要
};

其对应的处理代码片段都在 src/components/interactive/FootManager.astro 文件中。

CSS font-family 属性的值是一个按照优先级顺序的字体名称列表，被称为字体栈或字体族堆栈。浏览器会从列表的最左边开始尝试，如果用户设备上没有安装该字体或者无法下载该字体，浏览器就会尝试列表中的下一个字体，以此类推。最后通常会以一个通用字体族作为后备，确保内容在任何情况下都基本可读。

通用字体族是非常重要的后背方案（对应的名称不加引号）：

通用字体族	描述	典型示例
`serif`	衬线体，字符笔画末端有装饰性的小细节。显得传统、正式、优雅	Times New Roman, 宋体, SimSun
`sans-serif`	无衬线体，字符笔画末端干净，没有装饰。显得现代、简洁、易读	Arial, Helvetica, 微软雅黑, Microsoft YaHei
`monospace`	等宽字体，所有字符宽度相同。常用于显示代码、终端文本	Courier New, Consolas, Monaco
`cursive`	草书字体，模拟手写笔迹。具有艺术性，但可读性较差	Comic Sans MS, 楷体 (有时)
`fantasy`	奇幻字体，具有特殊艺术效果的字体。主要用于装饰	Impact, Papyrus
`system-ui`	系统默认字体，直接使用用户操作系统的默认界面字体	San Francisco (macOS), Segoe UI (Windows)

至于 fallback 字段里的其他值：

-apple-system：专为 macOS 和 iOS 系统设计的字体家族名称，用于调用苹果系统的默认字体（San Francisco）
BlinkMacSystemFont：针对 macOS 上使用 Blink 渲染引擎的浏览器（如 Chrome、Edge、Opera）的字体名称
Segoe UI：Misrosoft Windows 从 Vista 开始使用的默认界面字体
Roboto：Google 开发的 Android 系统和 Chrome OS 的默认字体

由此可见，fallback 字段值的基本核心思想是选择对应平台上的默认系统字体。

selected 字段主要作用是生成 CSS font-family 属性的堆叠，期间它会过滤掉传入的 id，其对应的单个字体项中 src 字段为空的：

// 获取选中的字体
const getSelectedFonts = () => {
  if (!fontConfig.enable || !fontConfig.selected) return [];

  const selectedIds = Array.isArray(fontConfig.selected)
    ? fontConfig.selected
    : [fontConfig.selected];

  return selectedIds
    .map((id) => fontConfig.fonts[id])
    .filter((font) => font && font.src); // 过滤掉系统字体和不存在的字体
};

也就是说，目前填的 selected: ["system"]，相当于 selected: []，直接使用 fallback 字段生成 font-family 属性的值：system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif。

对于成功被选择的每一个单个字体项，根据传入的 src 字段的链接类型会生成不同类型的新标签：

<!-- 字体样式表链接 -->{
  selectedFonts.map((font) => {
    // 判断是否为外部链接
    const isExternalUrl =
      font.src.startsWith("http://") ||
      font.src.startsWith("https://") ||
      font.src.startsWith("//");

    if (isExternalUrl) {
      // 外部字体链接 (如 Google Fonts, CDN等)
      return <link rel="stylesheet" href={font.src} />;
    } else {
      // 本地字体文件
      return (
        <style
          set:html={`
        @font-face {
          font-family: "${font.family}";
          src: url("${font.src}") ${font.format ? `format("${font.format}")` : ""};
          ${font.weight ? `font-weight: ${font.weight};` : ""}
          ${font.style ? `font-style: ${font.style};` : ""}
          ${font.display ? `font-display: ${font.display};` : ""}
          ${font.unicodeRange ? `unicode-range: ${font.unicodeRange};` : ""}
        }
      `}
        />
      );
    }
  })
}

单个字体项的各字段：

id：不影响渲染。用于内部查找、CSS 类名生成
name：不影响渲染。用于文档说明、可读性
family：影响渲染。用于 CSS font-family 属性
weight：仅影响渲染本地字体，由 @font-face 规则定义
display：仅影响渲染本地字体，定义本地字体的加载行为，用于 CSS font-display 属性

从结果上看，不管是使用外部字体链接还是本地字体文件，最终都会引入 @font-face 规则。因为外部字体链接通常是一堆 @font-face 规则的 CSS 文件的链接。

@font-face 规则允许使用自定义字体，需要在 CSS 文件的顶层定义或者放在 <style> 标签内，声明一个字体家族供后续使用。例如：

@font-face {
  font-family: 'Zen Maru Gothic';
  font-style: normal;
  font-weight: 300;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/zenmarugothic/v19/o-0XIpIxzW5b-RxT-6A8jWAtCp-cQWpCOfKK_7mX3yPCWUgO7n9RJZk8vDuG3WM.2.woff2) format('woff2');
  unicode-range: U+ffd7, U+ffda-ffdc, U+ffe0-ffe2, U+ffe4, U+ffe6, U+ffe8-ffee, U+1f100-1f10c, U+1f110-1f16c, U+1f170-1f1ac, U+1f200-1f202, U+1f210-1f234;
}

关键属性解释：

font-family：自定义字体的别名。将在后面的 CSS 规则中用这个名字来引用它
src：字体文件的实际路径。可以通过 url() 指定一个或多个源，浏览器会按顺序加载第一个它能识别的格式。format() 用于帮助浏览器识别字体格式
font-weight：告诉浏览器这个特定的字体文件对应哪种字重
font-style：告诉浏览器这个特定的字体文件是正常样式还是斜体
unicode-range：指定一个作用范围 —— 只有当网页中的字符落在指定的 Unicode 编码范围内时，才会下载并使用这个特定的字体文件

[!WARNING] 如果只提供了一个字体文件（比如常规粗细 400），但在 CSS 中使用了 font-weight: 700，浏览器会尝试通过算法加粗这个字体。这种模拟效果很粗糙，远不如真正的粗体字文件美观。

CSS font-display 是另一个关键属性，专门用于控制网页字体的加载和显示方式。

当使用 @font-face 引入一个网络字体时，浏览器可能的默认行为：

FOIT（闪烁的不可见文本）：在自定义字体加载完成之前，浏览器会将文字隐藏，显示一片空白
FOUT（闪烁的无样式文本）：浏览器先使用备用字体显示文本，等自定义字体加载完成后再切换回来

font-display 提供了一些值让我们去覆盖这种浏览器的默认行为。不过，为了理解这些值的含义，要先了解理解浏览器处理字体加载的三个关键时间段：

阻塞期：字体在加载时，浏览器会阻塞文本的显示，必须渲染不可见的备用字体。如果字体缓存中有，这个时期极其短
交换期：如果阻塞期结束字体还没加载好，浏览器会使用备用字体。之后一旦自定义字体加载完成，就好立即交换过来
失效期：如果交换期都结束了，字体还没加载好，浏览器就会放弃使用这个自定义字体，页面将一直使用备用字体

font-display 的不同值，能够调整这三个时间段的长度和行为：

值	行为描述	阻塞期	交换期
`auto`	浏览器默认行为。通常是 FOIT（隐藏文本直到超时）	不确定	不确定
`block`	文字会暂时不可见，然后立即使用备用字体显示，最后再交换回自定义字体	极短	无限
`swap`	立即用备用字体显示，等自定义字体加载好后立即交换	0	无限
`fallback`	文字会极短暂不可见，然后使用备用字体。如果之后自定义字体在较短的交换期内加载好了，就交换；否则就永远使用备用字体	极短	短
`optional`	文字会极短暂不可见，然后使用备用字体。是否交换取决于用户的网络连接和速度。如果用户在第一次访问时网络慢，字体可能永远不会加载	极短	0

由此可见，swap 是最常用、最推荐的选项，适用于我们这种正文等需要快速展示内容的情况。

在了解了字体配置和显示的机制后，就可以修改字体的相关配置：

// 字体配置
export const fontConfig = {
  enable: true, // 启用自定义字体功能
  preload: true, // 预加载字体文件以提高性能
-  selected: ["system"], // 当前选择的字体，支持多个字体组合
+  selected: ["misans-light", "misans-normal", "misans-medium",  "misans-semibold", "misans-bold"], // 当前选择的字体，支持多个字体组合
  fonts: {
-    // 系统字体
-    system: {
-      id: "system",
-      name: "系统字体",
-      src: "", // 系统字体无需 src
-      family:
-        "system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
-    },
-    // Google Fonts - Zen Maru Gothic
-    "zen-maru-gothic": {
-      id: "zen-maru-gothic",
-      name: "Zen Maru Gothic",
-      src: "https://fonts.googleapis.com/css2?family=Zen+Maru+Gothic:wght@300;400;500;700;900&display=swap",
-      family: "Zen Maru Gothic",
-      display: "swap" as const,
-    },
-    // Google Fonts - Inter
-    inter: {
-      id: "inter",
-      name: "Inter",
-      src: "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap",
-      family: "Inter",
-      display: "swap" as const,
-    },
+    // 小米字体 - MiSans Light
+    "misans-light": {
+      id: "misans-light",
+      name: "MiSans Light",
+      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Light.min.css",
+      family: "MiSans",
+      weight: 300,
+      display: "swap" as const,
+    },
    // 小米字体 - MiSans Normal
    "misans-normal": {
      id: "misans-normal",
      name: "MiSans Normal",
      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Normal.min.css",
      family: "MiSans",
      weight: 400,
      display: "swap" as const,
    },
+    // 小米字体 - MiSans Medium
+    "misans-medium": {
+      id: "misans-medium",
+      name: "MiSans Medium",
+      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Medium.min.css",
+      family: "MiSans",
+      weight: 500,
+      display: "swap" as const,
+    },
    // 小米字体 - MiSans Semibold
    "misans-semibold": {
      id: "misans-semibold",
      name: "MiSans Semibold",
      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Semibold.min.css",
      family: "MiSans",
      weight: 600,
      display: "swap" as const,
    },
+    // 小米字体 - MiSans Bold
+    "misans-bold": {
+      id: "misans-bold",
+      name: "MiSans Bold",
+      src: "https://unpkg.com/misans@4.1.0/lib/Normal/MiSans-Bold.min.css",
+      family: "MiSans",
+      weight: 700,
+      display: "swap" as const,
+    },
  }
  fallback: [
    "system-ui",
    "-apple-system",
    "BlinkMacSystemFont",
    "Segoe UI",
    "Roboto",
    "sans-serif",
  ], // 全局字体回退
};

这样就确保所选用的自定义字体涵盖了中文、英文、数字及日文字符集，并包含了常用的 300 到 700 字重。

在调试的过程中，我注意到 Inter 是一款可变字体，只需加载一个智能的字体文件，就可以让浏览器通过算法“生成”指定范围内的任何字重。其 @font-face 规则里的 font-weight 不管是多少都是指向同一个字体文件——Inter-Thin。

[!TIP] 在调试字体显示时，可按 F12 键打开浏览器的开发人员工具，切换到元素面板，接着按 Ctrl+Shift+C 键（或点击左上角的“选择元素”图标），在页面上点击要检查的元素。随后，在开发人员工具右下角找到并展开已计算面板，滚动到底部即可查看呈现的字体信息。

友链

Firefly 主题内置并默认开启友链页面。友链（友情链接）页面，初看只是列出跟本博客相关或有过联系的网站链接，从而提升对方网站的曝光率。但我在 AI 上询问得到了令人惊奇的回答，其中，对博主自身的好处有：

构建个人知识网络和灵感
塑造和表达博客的“个性”和“品味”
融入社区，获得归属感
潜在的流量回流和 SEO 益处

friendsConfig.ts 文件用于配置友链页面下的友链，例如可以添加 Mizuki 和 fuwari 这两个跟主题相关的友情链接。

我在文件里添加：

  // ...
  {
    "title": "Mizuki",
    imgurl: "https://mizuki.mysqil.com/_astro/avatar.Nvq3-FmN_Z28HWf5.webp",
    desc: "融合Android原生质感与二次元美学：Material Design 3规范下的Astro博客主题（Tailwind CSS实现）",
    siteurl: "https://github.com/matsuzaka-yuki/Mizuki",
    tags: ["GitHub", "Theme"],
    weight: 9,
    enabled: true,
  },
  {
    title: "fuwari",
    imgurl: "https://fuwari.vercel.app/_astro/demo-avatar.CxcI0ivM_1nbuVe.webp",
    desc: "✨A static blog template built with Astro.",
    siteurl: "https://github.com/saicaca/fuwari",
    tags: ["GitHub", "Theme"],
    weight: 9,
    enabled: true,
  },
  // ...

友链页面下面的自定义内容在 src/content/spec/friends.md 文件里，稍微修改一下：

...
- 站点名称: 夏夜流萤
- 站点描述: 飞萤之火自无梦的长夜亮起，绽放在终竟的明天。
- 站点链接: https://blog.cuteleaf.cn
+ 站点名称: 未来之蓝
+ 站点描述: 心怀蔚蓝愿景，脚踏实地前行。每一篇记录都是通向理想未来的坚实脚印。
+ 站点链接: https://xpfxzxc.github.io
头像链接: https://q1.qlogo.cn/g?b=qq&nk=7618557&s=640

## ✉️申请友链

- 请将您的网站信息发送邮件至：`xxx@xxx.com`
+ 请将您的网站信息发送邮件至：`xpfxzxc@gmail.com`
...

追番

Bangumi，名字来源于日语的“番组”（节目），致力于让阿宅们拥有一个轻松便捷独特的交流与沟通环境。目前设有五大分区：动画、书籍、音乐、游戏、三次元。

在 siteConfig.ts 文件里可以配置 Bangumi 用户 ID，用于在追番页面下显示该用户的收藏列表。

将 bangumi 字段下的 userId 的值改为自己的 Bangumi 用户 ID 即可：

// 追番配置
bangumi: {
-  userId: "1163581", // 在此处设置你的Bangumi用户ID
+  userId: "1175686", // 在此处设置你的Bangumi用户ID
},

赞助

赞助页面为博主提供一个渠道，来接受读者自愿性、直接的财务支持，通过支付宝/微信的一次性赞助，或者像爱发电等平台的定期赞助等。

sponsorConfig.ts 文件可以对赞助页面进行配置，需要将 public/assets/images/sponsor 目录下的 alipay.png 和 wechat.png 二维码图片替换成自己的收款二维码图片。

不过，微信 APP 和淘宝 APP 默认生成的收款二维码中自带头像。如果觉得这些收款二维码中的头像不好看，可以借助工具先解码二维码再重新生成二维码。更进一步的，甚至可以自定义二维码样式。

有两个网站用于方便解码和自定义生成二维码图片：

如果二维码的尺寸较大，可以使用 ImageMagick 工具去调整大小，例如：

magick wechat.png -resize 400x400 -filter Lanczos wechat.png

根据实际需求，我将 sponsorConfig.ts 文件内容改成：

import type { SponsorConfig } from "../types/config";

export const sponsorConfig: SponsorConfig = {
  title: "", // 页面标题，如果留空则使用 i18n 中的翻译
  description:
    "", // 页面描述文本，如果留空则使用 i18n 中的翻译
  usage:
-    "您的赞助将用于服务器维护、内容创作和功能开发，帮助我持续提供优质内容。", // 赞助用途说明
+    "您的赞助将用于内容创作，帮助我持续提供优质内容。", // 赞助用途说明
  // 是否显示赞助者列表
  showSponsorsList: true,
  // 是否在文章详情页底部显示赞助按钮
  showButtonInPost: true,

  // 赞助方式列表
  methods: [
    {
      name: "支付宝",
      icon: "fa6-brands:alipay",
      qrCode: "/assets/images/sponsor/alipay.png", // 收款码图片路径（需要放在 public 目录下）
      link: "",
      description: "使用 支付宝 扫码赞助",
      enabled: true,
    },
    {
      name: "微信",
      icon: "fa6-brands:weixin",
      qrCode: "/assets/images/sponsor/wechat.png", // 收款码图片路径
      link: "",
      description: "使用 微信 扫码赞助",
      enabled: true,
    },
-    {
-      name: "爱发电",
-      icon: "simple-icons:afdian",
-      qrCode: "",
-      link: "https://afdian.com/a/cuteleaf",
-      description: "通过 爱发电 进行赞助",
-      enabled: true,
-    },
-    {
-      name: "Github",
-      icon: "fa6-brands:github",
-      qrCode: "",
-      link: "https://github.com/CuteLeaf/Firefly",
-      description: "点个Star就是最大的支持",
-      enabled: true,
-    },
  ],

  // 赞助者列表（可选）
  sponsors: [
-    // 示例：已实名赞助者
-    {
-      name: "夏叶",
-      amount: "¥50",
-      date: "2025-10-01",
-      message: "感谢分享！",
-    },
-    // 示例：匿名赞助者
-    {
-      name: "匿名用户",
-      amount: "¥20",
-      date: "2025-10-01",
-    },
  ],
};

关于我

“关于我”页面就是博客里专门用来介绍“我是谁、为什么写这个博客、在做什么”的地方。

可在 src/content/spec/about.md 文件里修改“关于我”页面的内容。

我将该文件内容改为：

# 关于我 / About Me

-你好！我是 **夏叶** ，一个在数字世界中默默无闻的一片叶子。
+欢迎来到我的小角落。这里，主要是我写给自己看的一些文字和记录。很高兴你路过这里，并驻足阅读。
+
+我是 **xpfxzxc**。这个昵称很久前就开始使用了，但我忘记了这个昵称如何是取的，这个昵称可能没有什么含义吧。
+
+我是一个 98 后的听障人，不擅长言语沟通，头脑反应略慢，没创作灵感，平时喜欢独来独往、在网上冲浪。没有什么特长，唯一我比较懂的就是编程和游戏了，但在圈子里算是在底层水平，在日常上也不太拿得出手。我对编程曾充满热情，现在有点生疏，仍然“玩”得不太懂，但不想放弃。
+
+建立这个博客的初衷是我单纯地想试试部署好看的个人博客，还有记录以后学习到的技能知识。有时头脑里会有较多的想法，此时如果能够主动去梳理思路并记录下来，对当前和以后都会颇有收获。
+
+这里可能没有干货和指南，只有非常个人的、不成熟的想法和个人学习记录。如果你在我的文字里，找到了一丝共鸣，或者从中受到启发，或者从中成功解决某些疑惑，那将是我莫大的荣幸。
+
+欢迎你在想说话的时候，通过评论或邮件与我分享你的感受。我不一定会及时回复，但会认真阅读。

## 🛠️ 关于本站

-这个网站使用 **Astro** 框架构建，采用了 [Firefly](https://github.com/CuteLeaf/Firefly)模板
+这个网站使用 **Astro** 框架构建，采用了 [Firefly](https://github.com/CuteLeaf/Firefly) 主题。


**Firefly** 是一款基于 Astro 框架开发的清新美观且现代化个人博客主题，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

-
-**🖥️在线预览： [Firefly - Demo site](https://firefly.cuteleaf.cn/)**
-
-**🏠我的博客： [https://blog.cuteleaf.cn](https://blog.cuteleaf.cn/)**
-
-**📝Firefly使用文档： [https://docs-firefly.cuteleaf.cn](https://docs-firefly.cuteleaf.cn/)**
-
-**⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly** 
-
::github{repo="CuteLeaf/Firefly"}

-<img src="/assets/images/firefly.png" />
-
-

## 📫 联系方式

如果你想和我交流技术问题，分享有趣的想法，或者只是想打个招呼，欢迎通过以下方式联系我：

-* 💻 **GitHub**: [CuteLeaf](https://github.com/CuteLeaf)
-* ✉️ **Email**: [xiaye@msn.com](mailto:xiaye@msn.com)
+* 💻 **GitHub**：[xpfxzxc](https://github.com/xpfxzxc)
+* ✉️ **Email**：[xpfxzxc@gmail.com](mailto:xpfxzxc@gmail.com)

---

-*感谢你的来访！希望在这里能找到对你有用的内容。Firefly博客系统完全开源，如果喜欢的话，不妨给个GitHub点个Star ⭐ 支持一下！*
+*感谢你的来访！希望在这里能找到对你有用的内容。如果想感谢或者想支持我继续创作，可以访问我的赞助页面。*

// ...
// 广告配置2 - 完整内容广告
export const adConfig2: AdConfig = {
  title: "支持博主",
  content:
-    "如果您觉得本站内容对您有帮助，欢迎支持我们的创作！您的支持是我们持续更新的动力。",
+    "如果您觉得本站内容对您有帮助，欢迎支持我的创作！您的支持将激励我持续提供优质内容。",
  image: {
    src: "/assets/images/d2.webp",
    alt: "支持博主",
-    link: "about/",
+    link: "/sponsor/",
    external: false,
  },
  link: {
    text: "支持一下",
-    url: "about/",
+    url: "/sponsor/",
    external: false,
  },
  closable: true,
  displayCount: -1,
  padding: {
    // all: "1rem",
  },
};

然后开启该广告栏组件：

{
  // 组件类型：广告栏组件 2
  type: "advertisement",
  // 是否启用该组件
-  enable: false,
+  enable: true
  // 组件显示顺序
  order: 7,
  // 组件位置："sticky" 表示粘性定位
  position: "sticky",
  // CSS 类名
  class: "onload-animation",
  // 动画延迟时间
  animationDelay: 350,
  // 配置ID：使用第二个广告配置
  configId: "ad2",
},

收尾

完成了这些配置，个人博客便焕然一新，颇具个人风格了。接下来即可将变动提交并推送至线上。在此过程中，最好遵循 Git 最佳实践中的原子性提交原则，即每个 Commit 只包含单一、完整的逻辑变更，目的清晰，以避免产生中间状态。

元数据配置：

目前，siteConfig.ts 文件混杂着多个模块的改动，不适合一股脑全提交。虽然可以“倒回去分步提交”，但是有更省力的办法：用 git add -p <文件名> 交互式分块暂存，将一个文件的多处改动拆开，分批提交。

Git 会逐块显示差异，并询问如何处理每一块，例如：(1/5) Stage this hunk [y,n,q,a,d,j,J,g,/,s,e,p,?]?。可以输入以下常用命令：

命令	含义
`y`	接受（暂存）当前块
`n`	跳过当前块（不暂存）
`s`	将当前块进一步拆分成更小的块（如果可拆）
`e`	手动编辑当前块（高级用法，需熟悉 diff 格式）
`q`	退出，不再处理后续块
`?`	显示帮助信息

git add -p src/config/siteConfig.ts
git commit -m "chore: 更新站点元数据（标题、描述、关键词）"
git add public/assets/images/favicon.ico
git commit -m "chore: 更新 Favicon 图标"

站点 Logo 和名称：

git add -p src/config/siteConfig.ts
git rm public/assets/images/LiuYingPure3.svg
git add public/assets/images/logo.ico
git commit -m "chore: 更新站点 Logo 和名称"

个人基本资料：

git add src/config/profileConfig.ts
git add public/assets/images/avatar.webp
git commit -m "feat: 完善个人基本资料（头像、名称、介绍、社交媒体链接）" -m "- 更新个人基本信息（名称、介绍）" -m "替换个人头像图片" -m "调整现有社交媒体链接" -m "新增两个社交媒体平台链接"

站点公告：

git add src/config/announcementConfig.ts
git commit -m "feat: 更新站点公告配置" -m "- 更新公告标题和内容文案" -m "- 设置为不可关闭的永久显示模式" -m "- 移除公告链接按钮功能""

导航栏：

git add src/config/navBarConfig.ts
git commit -m "feat: 更新导航栏" -m "- 调整现有导航链接地址" -m "- 新增两个导航链接按钮"

背景壁纸：

git add -p src/config/siteConfig.ts
git add public/assets/images/d1.webp
git add public/assets/images/m1.webp
git commit -m "feat: 完善背景壁纸显示效果" -m "- 替换桌面端和移动端背景壁纸图片资源" -m "- 调整横幅模式下图片位置和主副标题内容" -m "- 优化全屏壁纸模式下遮罩层模糊程度" -m "- 完善壁纸来源信息显示设置"

主题色：

git add -p src/config/siteConfig.ts
git commit -m "feat: 更新主题色配置" -m "- 调整主题色的颜色" -m "- 锁定主题色选择器，对访客隐藏"

字体：

git add src/config/fontConfig.ts
git commit -m "feat: 更新字体配置" -m "- 调整 font-family 字体栈" -m "- 引入新的 @font-face 字体规则" -m "- 替换默认字体风格"

友链：

git add src/config/friendsConfig.ts
git add src/content/spec/friends.md
git commit -m "feat: 更新友链页面内容" -m "- 修改友链页面介绍文本内容" -m "- 新增两个友链条目"

追番：

git add src/config/siteConfig.ts
git commit -m "chore: 更新 Bangumi 用户 ID"

赞助：

git add src/config/sponsorConfig.ts
git add public/assets/images/sponsor/alipay.png
git add public/assets/images/sponsor/wechat.png
git commit -m "chore: 更新赞助页面信息和支付码" -m "- 调整赞助说明内容" -m "- 更新赞助方式列表" -m "- 替换支付宝和微信支付二维码" -m "- 清空赞助者列表"

关于我：

git add src/content/spec/about.md
git commit -m "chore: 更新关于我页面内容"

git add src/config/adConfig.ts
git add src/config/sidebarConfig.ts
git add public/assets/images/d2.webp
git commit -m "feat: 启用赞助引导广告栏" -m "- 开启赞助引导广告栏组件显示" -m "- 更新引导文案内容" -m "- 调整图片和按钮链接指向赞助页面" -m "- 替换展示图片"

最后，将代码推送到远程仓库：

git push origin custom

基于 Firefly 主题的 Astro 博客部署（二）：文章发布

Mon, 10 Nov 2025 00:00:00 GMT

在成功将博客站点部署到 GitHub Pages 上后，我打算暂不修改博客的个人资料（如个人名称、头像、介绍、公告、背景图等），而是先撰写文章再发布，所以首先研究一下这部分。

探索

在博客主页中可以看到，刚部署后的博客自带了几篇示例文章。这些示例文章是 Firefly 主题作者特意留下的，里面讲解了在撰写文章时可以用的 Markdown 语法。

文章位置

随便截取其中一篇示例文章中的几个字，然后在 VSCode 中按快捷键 Ctrl+Shift+F 或点击左侧栏 🔍 打开左侧栏的搜索栏，将几个字粘贴到搜索框中，很快就能够在 VSCode 左侧看见示例文章在项目中的具体位置：在 src/content/posts 目录下。

该目录下存放了所有文章，文章也可以存放在子目录中。文章在 src/content/posts 目录下的相对路径决定其最终的 URL。例如，文件 src/content/posts/firefly/hello-world.md 对应的访问 URL 为：https://<username>.github.io/posts/firefly/hello-world（<username> 需替换成 GitHub 用户名，下文同理）。

[!TIP] 创建子目录可以更好地组织文章和资源。

文章组成

每个文章文件的内容由两部分组成：

元数据：位于文章文件的开头，为 Markdown 文件本身提供了结构化信息（YAML 格式），由一对 --- 分隔符包裹着
文章主体：Markdown 格式的正文内容，紧接在元数据下方

元数据

从各个示例文章文件里，可以总结出元数据中可使用的字段：

title（必填）：文章标题
published（必填）：文章发布日期，日期格式 YYYY-MM-DD
updated：文章的最后一次更新日期，日期格式 YYYY-MM-DD
pinned：将文章置顶在文章列表顶部
description：文章的简短描述，显示在文章列表里
image：文章封面图片路径，有三种格式：
- 以 http 或 https 开头：网络图片
- 以 / 开头：public 目录下的图片
- 不带任何前缀：相对于 Markdown 文件的路径
tags：文章标签，字符串数组格式，例如：["技术", "随笔"]
category：文章分类
licenseName：文章内容的许可协议的显示名称
licenseUrl：文章内容的许可协议 URL
author：文章作者
sourceLink：文章内容的来源链接
draft：将文章标记为草稿。设为 true 后，文章仅在开发环境下可见，不会包含在最终发布的网站中
slug：自定义文章 URL 的末尾路径。如果未设置，将默认使用文章在 posts 目录下的相对路径（不含 .md 扩展名）作为路径
lang：仅当文章语言与 config.ts 文件中的网站语言不同时需要设置

字段的值即为该行冒号（：）之后的所有内容，因此通常无需使用引号。

以下是一篇示例文章中的片段：

---
title: Firefly 简单使用指南
published: 2025-10-11
pinned: true
description: "如何使用 Firefly 博客模板。"
image: "./cover.webp"
tags: ["Firefly", "博客", "Markdown", "使用指南"]
category: 博客指南
draft: true
---

这个博客模板是基于 [Astro](https://astro.build/) 构建的。对于本指南中未提及的内容，您可以在 [Astro 文档](https://docs.astro.build/) 中找到答案。

实操

了解了以上信息后，就可以开始撰写文章并发布了。不过，我打算先将自带的示例文章标记为草稿，保留而不是删除这些示例文章。这样，如果以后在撰写文章的过程中，一时想不起元数据或 Markdown 语法，那么可以在这些示例文章中查阅。

步骤

1. 标记示例文章为草稿

用 VSCode 打开本地项目，手动将在 src/content/posts 目录下的所有示例文章文件中元数据里的 draft: false 改为 draft: true。

接着在项目目录下运行：

git add .
git commit -m "chore: 标记自带的文章为草稿"

2. 撰写文章

注意到项目目录下的 package.json 文件里有可执行的脚本：

  "scripts": {
    "new-post": "node scripts/new-post.js"
  }

打开 scripts/new-post.js 文件，研究代码后知道：它接收文件名参数，并在 src/content/posts 目录下生成仅包含元数据模板的文章文件。

在项目目录下运行：

pnpm run new-post astro-firefly-blog-deploy/part1.md

这将在 src/content/posts 目录下创建子目录 astro-firefly-blog-deploy，并在该子目录下创建文章文件 part1.md。这文章文件包含着初始元数据模板：

---
title: part1.md
published: 2025-10-30
description: ''
image: ''
tags: []
category: ''
draft: false 
lang: ''
---

通过 URL 路径 /posts/astro-firefly-blog-deploy/part1 访问到该文章。

为了避免使用嵌套过多的 URL 子路径，添加 slug: astro-firefly-blog-deploy-part1 到元数据块里。这样，可以通过 URL 路径 /posts/astro-firefly-blog-deploy-part1 访问到该文章。

3. 发布文章

修改元数据，并撰写文章主体后，就可以将文章发布出去了。

在项目目录下运行：

git add .
git commit -m "feat: 添加文章 '基于 Firefly 主题的 Astro 博客部署（一）：从零到 GitHub Pages'"
git push origin custom

扩展内容：Front Matter

在与 AI 沟通元数据相关内容的时候，注意到 AI 对这些元数据的格式和使用的单词颇为熟悉。经过深入询问才知道：其实前面所说的元数据有个标准名称叫做 Front Matter。

定义

Front Matter 是位于文件（通常是 Markdown 或 HTML 文件）顶部区域的一段特定格式（通常是 YAML 格式）的代码块，文件正文就写在这个 Front Matter 块的下方。

作用

用于为文章或页面定义元数据，告知静态网站生成器如何处理这些文件：

内容和页面分离：无需改动模板代码，就能通过简单的键值对控制每个页面的行为和展示方式
驱动网站生成
- 为文章排序（根据 date）
- 生成标签页和分类页（根据 tags 和 category）
- 在列表中显示文章标题、摘要和封面（根据 title、description 和 image）
控制构建行为：像 draft: true 这样的键值对告知生成器：“这篇文章是草稿，在正式构建时请忽略它”

扩展内容：从文章文件到文章展示

已经知道 Firefly 主题项目里 src/content/posts 目录存放着文章内容。在构建静态站点时，Astro 会为非草稿文章逐一生成对应的 HTML 页面和路由。要进一步了解这个过程是如何在代码中体现的，就需要对 Astro 框架的相关知识有所了解。

官方文档相关资料

解析项目代码

接下来，将结合 Astro 的相关知识点，来解析项目代码。

页面文件

src/pages 目录下的文件（支持 .astro、.ts 等格式）会被 Astro 自动识别为页面。

下面展示了项目 src/pages 目录的实际结构，其中的每一个文件都对应一个或多个页面：

src/pages/
├── 404.astro
├── [...page].astro
├── about.astro
├── anime.astro
├── archive.astro
├── friends.astro
├── og/
│   └── [...slug].png.ts
├── posts/
│   └── [...slug].astro
├── robots.txt.ts
├── rss.astro
└── rss.xml.ts

静态路由

Astro 使用基于文件的路由，根据项目 src/pages 目录下的文件结构来构建链接，自动将它们作为网站页面。

这意味着，虽然 Astro 项目没有单独的路由配置，但依然可以通过页面文件在 src/pages 目录中的路径推断出最终生成的路由。例如：

mysite.com/about -> src/pages/about.astro
mysite.com/404   -> src/pages/404.astro

注：像 [...slug].astro 这样采用特殊命名的页面文件属于动态路由，不属于静态路由的范畴。

组件脚本

以 .astro 为后缀的文件是 Astro 组件，每个 Astro 组件由组件脚本和组件模板两部分组成。

Astro 使用代码围栏 --- 来识别组件脚本部分。虽然这种语法形式与 Front Matter 相似，但是两者作用不同：组件脚本内编写的是 TypeScript 代码，而非元数据。

后续会提到组件脚本中的一些作用和组件模板的一些语法。

动态路由

类似 [...slug].astro 这样文件名中包含方括号的 Astro 组件用于实现动态路由。这类文件根据传入的动态参数，将文件名内方括号对应的部分替换为具体的参数值，生成对应的多个路由和匹配页面。

例如，对于 src/pages/posts/[category]/[post].astro 文件，当传入参数 { category: 'demo', post: 'hello-world' } 时，将会生成如下路由：

mysite.com/pages/posts/demo/hello-world -> src/pages/posts/[category]/[post].astro

剩余参数（例如：[...slug]）可以匹配任何深度的文件路径。

项目中 src/pages/posts 目录下的 [...slug].astro 文件，自然地令人联想到文章页面的生成和路由跟这页面文件有关，且动态路由参数的值与 slug 的值有关。

在静态站点生成模式下，因为必须在构建时确定所有路由。所以，在组件的脚本部分中，需要通过导出 getStaticPaths() 函数来指定所有可能的参数组合。该函数返回一个对象数组，其中每个对象的 param 字段定义了 slug 参数的具体取值。

// ...
export async function getStaticPaths() {
  const blogEntries = await getSortedPosts();
  return blogEntries.map((entry) => ({
    params: { slug: entry.slug },
    props: { entry },
  }));
}
// ...

这代码片段对应了之前提到的：

通过修改文章元数据里的 slug 字段值，能够更改文章的访问路径
组件脚本的作用之一是通过导出特定函数，向框架提供所需信息

内容集合

根据前面的分析，文章内容存储在 src/pages 目录之外，这意味着默认情况下不会为内容生成页面和路由。文章页面的生成好像跟 src/content/posts 目录无关。那么，Astro 是如何定位文章文件、并为每篇文章生成对应的页面和路由的呢？

答案是通过内容集合。通过将 src/content/posts 目录定义为内容集合，让 Astro 统一管理其中的内容，每篇博客文章都作为该集合中的一个条目。

Astro 会自动扫描 src/content 目录下的所有子目录，将每个子目录识别为一个独立的内容集合。通过在 src/content 目录下添加 config.ts 文件，可以定义 Schema 来规范集合中内容的 Front Matter 或条目数据，这些 Schema 会通过 Zod 进行数据验证，确保数据格式的一致性。

项目中 src/content/config.ts 文件内容如下：

import { defineCollection, z } from "astro:content";

const postsCollection = defineCollection({
	schema: z.object({
		title: z.string(),
		published: z.date(),
		updated: z.date().optional(),
		draft: z.boolean().optional().default(false),
		description: z.string().optional().default(""),
		image: z.string().optional().default(""),
		tags: z.array(z.string()).optional().default([]),
		category: z.string().optional().nullable().default(""),
		lang: z.string().optional().default(""),
		pinned: z.boolean().optional().default(false),
		author: z.string().optional().default(""),
		sourceLink: z.string().optional().default(""),
		licenseName: z.string().optional().default(""),
		licenseUrl: z.string().optional().default(""),

		/* Page encryption fields */
		encrypted: z.boolean().optional().default(false),
		password: z.string().optional().default(""),

		series: z.string().optional(),

		/* For internal use */
		prevTitle: z.string().default(""),
		prevSlug: z.string().default(""),
		nextTitle: z.string().default(""),
		nextSlug: z.string().default(""),
	}),
});
const specCollection = defineCollection({
	schema: z.object({}),
});
export const collections = {
	posts: postsCollection,
	spec: specCollection,
};

Astro 提供了辅助函数 getCollection()，用于获取指定集合的全部内容，并以数组形式返回所有条目。

在 src/pages/posts/[...slug].astro 文件中，通过调用了 getSortedPosts() 函数间接使用了 getCollection() 函数，最终获得了经过排序的博客文章数组。

以下是第一篇博客文章的条目结构：

{
  id: 'astro-firefly-blog-deploy/part1.md',
  data: {
    title: '基于 Firefly 主题的 Astro 博客部署（一）：从零到 GitHub Pages',
    published: 2025-10-29T00:00:00.000Z,
    draft: false,
    description: '记录了自己是如何使用开源的 Firefly 主题，在 GitHub Pages 上从零开始部署基于 Astro 的个人博客。',
    image: '',
    tags: [
      '博客部署',
      'Astro',
      'Firefly',
      '开源主题',
      'GitHub Pages',
      'GitHub Actions',
      'Git'
    ],
    category: '实操记录',
    lang: '',
    pinned: false,
    author: '',
    sourceLink: '',
    licenseName: '',
    licenseUrl: '',
    encrypted: false,
    password: '',
    prevTitle: '',
    prevSlug: '',
    nextTitle: '',
    nextSlug: ''
  },
  body: '## 前言\r\n' +
    '\r\n' +
    '...',
  filePath: 'src/content/posts/astro-firefly-blog-deploy/part1.md',
  digest: '474c5b5ac94b1108',
  rendered: {
    html: '<section><h2 id="前言">前言<a class="anchor" href="#前言">....',
    metadata: {
      headings: [Array],
      localImagePaths: [],
      remoteImagePaths: [],
      frontmatter: [Object],
      imagePaths: []
    }
  },
  collection: 'posts',
  slug: 'astro-firefly-blog-deploy-part1',
  render: [Function: render]
}

观察上面的条目可以发现，虽然文章文件路径为 src/content/posts/astro-firefly-blog-deploy/part1.md，但其 slug 字段的值为 astro-firefly-blog-deploy-part1。值得注意的是，尽管在 src/content/config.ts 文件中的 Scheme 中并未定义 slug 字段，但仍然成功获取到了文章 Front Matter 中设置的 slug 值。

由于 slug 字段与 data 字段处于同一层级，猜测 Astro 会自动提取 Front Matter 中的 slug 字段值。这点可以通过检查其他未设置 slug 值的文章条目，观察其行为差异来验证。

在动态路由的实现中，通过在组件脚本中导出 getStaticPaths() 函数，其中该函数返回包含 params 字段的对象数组，每个 params 对象都包含一个 slug 字段。这意味着，通过修改文章 Front Matter 中的 slug 值，能够控制文章最终生成的访问路径。

[!NOTE] 在撰写本文章的时候，虽然 Firefly 主题使用的 Astro 版本是 5.15.3，但是它使用的内容集合 API 是旧版的。Astro 5 引入了内容层 API 用于替代旧的版本 API。例如，在 Astro 5 中，要定义集合，必须在项目中创建 src/content.config.ts 文件，且在使用 defineCollection() 函数的时候必须配置 loader 用于加载数据源。再比如，渲染方法 entry.render() 被 render(entry) 函数取代。如果在项目里 src/content/config.ts 文件中强行添加 loader: glob({ ... })，也就启用了 Astro 5 的新内容层 API，这导致项目里 entry.render() 调用失败。

变量注入

根据前面的分析，文章条目对象的 data 字段中存储着文章元数据。

组件脚本的另一个重要作用是创建可在模板中使用的变量。这些变量通过 Astro 的组件模板语法在组件模板中被引用。

具体实现的过程如下：将文章条目对象通过 getStaticPaths() 函数返回对象的 props 字段传入后，可以在组件脚本里通过 Astro.props 获取该对象，并基于其声明变量。随后，可以使用类似 JSX 语法在组件模板中使用。

通过在组件模板中使用组件脚本中定义的数据和值，最终生成动态创建的 HTML：

// ...
export async function getStaticPaths() {
  const blogEntries = await getSortedPosts();
  return blogEntries.map((entry) => ({
    params: { slug: entry.slug },
    props: { entry },
  }));
}

const { entry } = Astro.props;
// ...

---
<MainGridLayout
  banner={entry.data.image}
  title={entry.data.title}
  description={entry.data.description}
  lang={entry.data.lang}
  setOGTypeArticle={true}
  postSlug={entry.slug}
  headings={headings}
>
<!-- ... -->
</MainGridLayout>

基于 Firefly 主题的 Astro 博客部署（一）：从零到 GitHub Pages

Mon, 03 Nov 2025 00:00:00 GMT

前言

前几天，我像平时一样在网站 LINUX DO 上逛帖子，偶然看到有人开源了一个名为 Firefly 的博客主题模板。在查看了主题的预览效果图并访问了演示站点后，我认为它设计精致、外观美观，且集成了众多的实用功能。

::github{repo="CuteLeaf/Firefly"}

回顾

我回顾了下过去的几年经历：

学过不少编程知识，但大部分现在都忘了
曾经有过主动总结知识的想法，但苦于不知将记录存放到哪里
曾经有过搭建个人博客的想法，但一直未付诸实践，甚至觉得没必要
今年频繁与 AI 交流，许多问题反复提问，相关知识点也被反复提及，但我仍未记住；相关问题和回答分散到各网站上，不方便去检索

需求

想了想，现在是时候去试着部署个人博客玩玩了！我的需求很简单：

快速开始，且可定制化
界面风格现代，外观精美
无需支付服务器和域名的费用
不想太多人关注我的博客
不想在不知名的网站上写博客
能够获取主题更新
以后能为主题贡献代码

平台选择

根据需求，与 AI 沟通并查阅相关资料后，我觉得可以借助该开源项目在 GitHub Pages 上部署个人博客网站。

我进行了以下几方面的考虑，最终选择将 GitHub Pages 作为博客托管平台。

完全免费

GitHub Pages 对公开仓库免费提供静态网站托管服务，无需支付服务器或流量费用。我不用再操心服务器域名的费用，同时也让网站启用了 HTTPS。

长期稳定

近几年，伴随大语言模型的冲击，问答社区、博客等网站，比如：CSDN、简书、StackOverflow 等网站迅速走向衰弱。然而，GitHub 作为代码托管平台反而越来越火。从长远来看，GitHub 会倒闭的可能性极低。

与 GitHub 无缝集成

博客网站、博客内容以文件以代码形式存在，天然支持版本控制。借助 GitHub 页面 UI 和 Git，可以很好地处理好各方的远程仓库和本地仓库的版本控制。GitHub 自带的 Discussion 又能免费地作为博客文章的讨论区。

部署简单，可自动化

只需将静态文件推送到远程仓库指定的分支，GitHub 就会自动构建并发布。更进一步，允许借助 GitHub Actions 自定义自动化流程。

实操

我打算先让博客上线运行，之后再逐步调整。

思路

作为博客网站，最重要的是展示博客文章内容。博客文章内容相对稳定，除非博主更新文章，不然用户反复刷新网页，网页的内容也不会变化。用户通常是通过点击链接，从一个页面跳转到另一个页面，几乎不需要再进行额外的复杂交互。

Astro 作为静态站点生成器，构建时生成的 HTML 文件可直接放到免费的托管平台上运行，不需要服务器。生成的网页不带多余的 JavaScript（可以按需加载），加载速度飞快，对 SEO 友好。由此可见，Astro 很适配我的需求。

关于仓库的版本控制和管理：

我想能轻松拉取原 Firefly 代码的更改，所以需要先 fork 一份到我的仓库。
我想能定制化代码、发表博客文章，所以需要 clone 到本地仓库。
我想能选择性地获取原 Firefly 代码的更新、定制化代码、发表博客内容，所以需要新建分支 custom。
我想以后能贡献代码给原 Firefly，所以不能改动主分支 master。
我想将 https://<username>.github.io 作为我的博客主页，所以我需要新建仓库 <username>.github.io（将 <username> 替换为 GitHub 用户名，下文同理）。
我想让我对博客网站的更改，能自动被推送到线上，所以我需要在我的 Fork 仓库配置一个 GitHub Actions 工作流：每当向我的 Fork 仓库推送代码时，GitHub Actions 会自动构建静态网站，并将生成的文件推送到 <username>.github.io 仓库，从而更新线上站点。

思路理清了后，就开始动手实操了。

步骤

1. 创建仓库 `<username>.github.io`

在创建仓库页面中，依次填入以下内容：

Repository name：<username>.github.io
Description：Personal blog website hosted on GitHub Pages

直接点击 Create Repository 按钮创建仓库，无需调整其他选项。

2. `Fork` 原项目到我的仓库

打开项目 Firefly 主页，点击页面右上角的 Fork 按钮，无需修改任何选项，直接点击 Create fork 按钮即可。

[!NOTE] 原项目使用 master 作为默认分支，而非现在常见的 main。

3. 将我的 Fork 仓库 `clone` 到本地

在项目目录下运行：

git clone git@github.com:<username>/Firefly.git
code Firefly

这将用 VSCode 打开刚拉取下来的项目。

4. 在本地仓库创建并切换到 `custom` 分支

在项目目录下运行：

git branch custom
git checkout custom

5. 禁用会报错的 workflow 文件

在实操过程中，我发现 .github/workflows 目录下工作流文件 biome.yml 和 build.yml 运行时会报错。考虑到后续可能需要修改，暂不删除，而是通过在文件名末尾添加 .disabled 后缀来禁用它们。

6. 修改 workflow 文件以自动部署到另一个仓库

根据之前的思路：每当接收到推送事件时，自动构建静态网站，并将生成的文件推送到 <username>.github.io 仓库。

需要修改 .github/workflows 目录下的 deploy.yml 文件：

name: Deploy to Pages Branch

on:
-  # 每次推送到 `main` 分支时触发这个"工作流程"
-  # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
+  # 每次推送到 `custom` 分支时触发这个"工作流程"
  push:
-    branches: [ main ]
+    branches: [ custom ]
  # 允许你在 GitHub 上的 Actions 标签中手动触发此"工作流程"
  workflow_dispatch:

# 需要写入权限来推送到pages分支
permissions:
  contents: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9.14.4
          run_install: false
          
      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile
      
      - name: Build site
        run: pnpm run build
      
      - name: Deploy to pages branch
        uses: JamesIves/github-pages-deploy-action@v4
        with:
-          branch: pages # 部署到pages分支
+          token: ${{ secrets.GH_PAT }} # 需要在仓库的Settings->Secrets and variables->Actions中添加GH_PAT，该Token需要有写入权限
+          repository-name: <username>/<username>.github.io # 你的GitHub Pages仓库名称
+          branch: main # 部署到custom分支
          folder: dist # Astro默认构建输出目录
          clean: true # 清理目标分支中的旧文件

7. 创建 PAT

点击 GitHub 账号右上角头像 → 选择 Settings → 左侧边栏点击 Developer settings → 点击 Personal access tokens → 选择 Fine-grained tokens → 点击右侧 Generate new token。

在创建页面中，依次填写以下内容：

Token name：为令牌命名（如：blog-deploy）
Expiration：设置过期时间（如：90 days）
Repository access：选择 Only select repositories，并仅勾选 <username>.github.io
Permissions：点击 Add permissions，添加以下三项权限：
- Contents → 设为 Read and write（用于更改仓库内容）
- Pages → 设为 Read and write（用于部署 GitHub Pages）
- Metadata → 保持默认（Read-only，自动包含）

这样可避免生成的令牌可访问的仓库范围过广或权限过大。

点击 Generate token 按钮，并记录下生成的令牌。

8. 创建环境变量

在我的 Fork 仓库页面，点击顶部导航栏的 Settings → 左侧边栏点击 Secrets and variables → 选择下拉项 Actions → 点击右侧 New repository secret 按钮。

在创建页面中，依次填写以下内容：

Name：GH_PAT
Secret：粘贴刚才保存的令牌

点击 Add secret 按钮。

9. 修改部署地址

根据 Astro 官方文档里的部署指南，需要将 astro.config.mjs 文件里的 site 改成 GitHub Pages 部署地址：

export default defineConfig({
-    site: "https://demo-firefly.netlify.app/",
+    site: "https://<username>.github.io",
})

10. 添加 `.nojekyll` 文件

在使用 Astro 构建项目时，Astro 会在 dist 输出目录中生成一个 _astro 文件夹，其中包含 JavaScript 代码和静态资源。

GitHub Pages 对于基于分支自动构建的方式，会默认启用 Jekyll 构建引擎，而 Jekyll 会自动忽略所有以下划线 _ 开头的文件和目录。

因此，当基于分支把 Astro 构建出的 dist 目录部署到 GitHub Pages 时，_astro 目录会被 Jekyll 忽略，不会被发布，这导致网页显示不正常，功能异常。

解决办法很简单，在部署目录 dist 添加一个名为 .nojekyll 的空文件，用于告诉 GitHub Pages：不要用 Jekyll 处理这个站点。

实际上，在我的项目 public 目录下添加空文件 .nojekyll 即可。因为 Astro 在构建站点时，会将它复制到 dist 部署目录。

在项目目录下运行：

touch public/.nojekyll

11. 提交 commit 并推送代码到远程仓库

在项目目录下运行：

git rm .github/workflows/biome.yml
git add .github/workflows/biome.yml.disabled
git rm .github/workflows/build.yml
git add .github/workflows/build.yml.disabled
git commit -m "chore: 临时禁用冗余的 workflow 文件"

git add .github/workflows/deploy.yml
git commit -m "chore: 调整工作流文件中的引用 main 为 custom，并使打包后的文件部署到另一个仓库的 main 分支上"

git add astro.config.mjs
git commit -m "修改部署地址"

git add public/.nojekyll
git commit -m "fix: 添加文件 public/.nojekyll 以正确提供 _astro 目录中的文件"

git push origin custom

12. 验证部署结果

打开我的 Fork 仓库页面，点击顶部导航栏的 Actions
等待最新的工作流运行完成，确保没有发生错误
打开 <username>.github.io 仓库页面，可看到已部署好的站点文件。GitHub Pages 会自动从 main 分支部署站点，无需额外操作
点击顶部导航栏的 Actions，等待 GitHub Pages 部署站点完成
访问 https://<username>.github.io，观察页面是否正常显示
按 F12 键打开开发人员工具，切换到控制台面板，检查其中是否有严重错误报告信息

后续

当上游更新代码后，可在我的 Fork 仓库页面点击 Sync fork 按钮同步更新
建议在 custom 分支上进行个性化定制（如撰写博客文章）
当本地仓库需要同步上游更新时，有以下方式：
- 完整同步：在 master 分支上拉取上游最新更改，再通过 git merge master 或 git rebase master 将全部变更整合到 custom 分支
- 部分同步：使用 git cherry-pick 选取特定提交，或通过 git checkout master -- <file> 仅更新个别文件
当想为原主题仓库贡献代码时，可先在 master 主分支上拉取上游最新更改。然后，基于主分支创建新的分支，并根据工作性质合理命名，例如新功能使用 feature/xxx，Bug 修复使用 fix/xxx。在新分支上完成修改并提交后，将其推送到自己的 Fork 仓库。最后向原主题仓库发起 Pull Request 请求合并分支。