溯月馆

零基础搭建并装修精致优雅的二次元博客网站

Sat, 24 Oct 2026 06:25:41 GMT

Why Shirone？

在检索“如何将大肥鱼接入 QQ 机器人”的教程时，我偶然刷到一个看起来不错的博客，翻了几个友链发现用的都是同一套主题，于是记下了那个主题的名字——Mizuki。一番调研后了解到该主题仓库已停止维护了，项目重构升级后迁到了 Shirone。

当时主要是看中了该主题提供的丰富的独立页面，甚至还有追番展示页面。当然，考虑到站点迁移的工作量与我并不充裕的时间，这些还不足以让我下定决心放弃现有的博客。

决定性的因素是该主题模板提供的一整套架构设计与性能优化方案，其中双仓架构、实时监听与构建优化尤为突出，切实解决了此前搭建与维护博客遇到的一些痛点。

遂决定忙里偷闲也要把博客搬过去。

于是按照某种惯例，这次也分享一下搭建博客的大致步骤与过程中踩的一些坑。

::: caution[注意]

本教程仅提供我在建站过程中采用的方案的大致指引，本质是对官方文档的提炼、归纳与补充，仅代表个人观点。该主题模板提供了丰富的方案选择，请查阅官方文档了解项目全貌。

开发过程中如遇到问题，先仔细查看报错信息，然后查官方文档，主题制作组提供了详尽的帮助文档，覆盖各功能模块的方方面面。若无法独立解决，再问Agent（注意工作边界，尽量别让它动主题代码）。最后实在没招了可以去制作组QQ群求助，群号见视频简介。

:::

前置准备

环境配置

首先需要准备以下工具：

工具	作用	举例
AI Agent	核心出装，零基础的基础	Codex、DSH、omp 等，视自身需求选用
IDE	编辑代码	微软大战代码
Markdown 编辑器	写文章	Obsidian，或安装 IDE 插件
Git	拉取上游仓库更新与推送本地仓库	安装一个适配本机的版本即可
GitHub	托管网站仓库，部署网页（可选）	注册账号用网页版即可
Node.js	管理主题模板依赖与执行内置命令	建议安装最新版，并在选择版本时注意适配 pnpm

然后找一个合适的目录用于存放网站文件，不妨称之为 /site。

在该目录下打开终端并执行环境检查：

git -v
node -v
pnpm -v

正常输出版本号则环境已配好。

主题准备

然后拉取两个仓库：

git clone https://github.com/LyraVoid/Shirone.git theme
git clone https://github.com/LyraVoid/Shirone-Content.git blog-content

这里的 theme 和 blog-content 为主题仓和内容仓的文件夹命名，可以任意定义，下文统一以此指代主题仓和内容仓，注意命令中的命名替换。

然后在 GitHub 上创建两个仓库：一个公共仓库用于托管主题仓，一个私有仓库 blog-content（内容仓）用于托管 /blog-content。内容仓的命名可以任意定义，主题仓的命名规则见下方须知。

::: caution[博客仓库命名须知]

若采用 GitHub Pages 用户站（https://你的用户名.github.io），主题仓的命名必须是 你的用户名.github.io；若采用项目站（https://你的用户名.github.io/仓库名），仓库名可任意定义。

:::

接着，我们需要将两个仓库的远程地址重定向为自己的仓库。

主题仓：

cd theme
# 将原地址重命名为upstream
git remote rename origin upstream
# 添加自己的仓库地址
git remote add origin git@github.com:你的用户名/你的用户名.github.io.git
# 最后检验仓库地址状态
git remote -v

若两个仓库地址都在，则配置完成。

内容仓：

cd blog-content
git remote rename origin upstream
git remote add origin git@github.com:你的用户名/blog-content.git
git remote -v

同上。

如此配置，推送时 push 到 origin，更新时 fetch 自 upstream。需要注意的是，要严格贯彻双仓分离的原则，自己的配置、文章、图片等各种项目资产全部放到内容仓，主题仓中不作任何改动。在 merge 时，主题仓以上游为准，内容仓的情况比较复杂，可能存在一些冲突（如配置表更新）需要手动微调。

::: tip[为何分双仓建站]

主题仓用于存放主题代码并接收上游仓库更新，内容仓用于存放自定义配置、文章、图片等个人资源。这样做有以下好处：

拉取上游更新时，避免处理各种合并冲突；
若主题仓托管到公共仓库，内容仓可独立托管到私有仓库，防止内容泄露；
内容仓专注于内容创作而无须关心代码实现，更易上手。详见内容分离架构概览 | 文档 | Shirone Docs。

:::

为了让主题仓能读取内容仓的文件，需要在 /theme 下新建一个文件 .env，内容建议直接从已有的 .env.example 复制粘贴，然后将被注释的三行代码编辑为：

CONTENT_DIR="blog-content的绝对目录"
CONTENT_REPO_URL="https://github.com/你的用户名/blog-content.git"
CONTENT_REPO_REF="main"

然后在同目录下的 .gitignore 文件中新增一行：

.env

这样就可以防止环境变量被上传到主题仓库。

最后在主题仓安装依赖，并预览确认默认网页的状态：

cd theme
pnpm install
pnpm dev

命令运行输出绿字后，打开浏览器 localhost:4321 即可本地预览网页状态。

至此，就可以开始正式的网站搭建了。

初识 Shirone

项目概览

首先大概看一下 /theme 的文件结构：

├── public/ # 纯静态资源（favicon、robots.txt 等无需编译的文件）
│   └── favicon.svg # 站点主图标
├── src/ # 核心源码目录
│   ├── assets/ # 由 Vite / Astro 处理的静态资源（默认横幅、插画）
│   │   └── fonts/ # 本地字体文件与构建期子集产物
│   ├── components/ # Svelte 5 原子组件与 Astro 业务模块
│   ├── config/ # 强类型站点配置文件群
│   ├── content/ # Markdown 文章与独立数据集合
│   ├── i18n/ # 多语言文案与语言包
│   ├── integration/ # Astro 集成入口（路由注入、字体子集、图标收集、缩略图生成）
│   ├── layouts/ # 顶层页面布局（Layout.astro、MainGridLayout.astro）
│   ├── pages/ # 静态路由与动态页面生成
│   ├── styles/ # M3 Expressive Tokens 与全局 CSS 样式
│   ├── user/ # 用户配置覆盖层（由 content:sync 生成，勿手改）
│   └── utils/ # 算法工具库（WebCrypto、动态配色、音频单例）
├── scripts/ # 自动化构建与离线同步脚本
│   └── anime/ 
│       └── sync.mjs # Bangumi / Bilibili 追番数据同步入口
├── astro.config.mjs # Astro 顶层配置文件（集成 Svelte、Swup、Tailwind）
├── svelte.config.js # Svelte 5 编译器配置（启用 Runes 响应式）
├── tsconfig.json # TypeScript 路径映射与严格模式
├── package.json # 项目依赖与脚本命令
└── pnpm-lock.yaml # 锁版本清单

其中，主题仓在双仓模式下一般不需要改动，了解大致用途即可。

因为网站在执行构建时，会用内容仓中的配置覆盖主题仓的配置。我们需要关注的是 /blog-content ：

├── .github/
│   └── workflows/
│       └── trigger-build.yml.example # 跨仓触发 GitHub Actions 模板
├── config/                  # 全站声明式配置 YAML 文件群
│   ├── site.yaml            # 站点标识、时区、色彩与横幅壁纸
│   ├── permalink.yaml       # 全局文章固定链接与占位符规则
│   ├── profile.yaml         # 博主头像、昵称、签名与社交外链
│   ├── nav-bar.yaml         # 顶部导航栏条目与下拉菜单
│   ├── sidebar.yaml         # 侧边栏布局与组件清单
│   ├── font.yaml            # 全站字体与字形裁剪配置
│   ├── anime.yaml           # 追番追剧页面与同步数据源
│   ├── music.yaml           # 侧栏播放器模式与歌单配置
│   ├── comment.yaml         # 评论系统配置（Twikoo / Giscus / Waline）
│   ├── article.yaml         # 文章排版与阅读提醒配置
│   ├── post-list.yaml       # 首页文章列表与分页模式
│   ├── devices.yaml         # 数码装备分类与筛选规则
│   ├── games.yaml           # 游戏展示分类与筛选规则
│   ├── projects.yaml        # 开源项目分类与阶段规则
│   ├── skills.yaml          # 技能图谱分类与熟练度规则
│   ├── timeline.yaml        # 大事记时间线分类规则
│   ├── friends.yaml         # 友情链接分组规则
│   ├── announcement.yaml    # 全局浮动公告栏配置
│   ├── expressive-code.yaml # 代码高亮与代码块行号
│   ├── context-menu.yaml    # 桌面端右键增强菜单与操作项
│   ├── fab.yaml             # 悬浮动作按钮 (FAB)
│   ├── image-bloom.yaml     # 图片泛光视觉滤镜
│   ├── license.yaml         # 原创知识共享协议 (CC)
│   ├── llms.yaml            # 大模型 AI 检索增强
│   ├── umami.yaml           # Umami 访问统计分析
│   ├── series.yaml          # 系列连载展示与索引配置
│   ├── footer.yaml          # 页脚文案与备案信息
│   └── footer.html          # 自定义注入的页脚 HTML 片段
├── content/                 # 原创文章、说说与页面文案
│   ├── posts/               # Markdown 与 MDX 博客长文 (如 guide.md)
│   ├── moments/             # 动态生活说说 (如 first-moment.md)
│   ├── series/              # 系列连载实体与导读 (如 guide-series.md)
│   └── spec/                # 特殊页面文案 (about.md, friends.md)
├── data/                    # 结构化数据实体 TypeScript 模块
│   ├── anime.ts             # 追番本地数据快照
│   ├── compass.ts           # 推荐导航与罗盘条目
│   ├── devices.ts           # 硬件与数码设备清单
│   ├── games.ts             # 游戏展示清单
│   ├── friends.ts           # 友情链接清单
│   ├── music.ts             # 本地音乐曲目数据
│   ├── projects.ts          # 开源与个人项目清单
│   ├── skills.ts            # 技能图谱与熟练度数据
│   └── timeline.ts          # 个人大事记时间线数据
├── assets/                  # 自己的高清图片 (同步到代码仓 src/assets/，构建时自动压缩)
│   ├── images/
│   │   ├── banner/          # 顶部横幅背景图，分 desktop/ 与 mobile/ 两套
│   │   ├── music/           # 本地音乐的封面图
│   │   └── author.jpg       # 博主头像
│   └── games/               # 游戏页面的横幅大图
├── public/                  # 静态多媒体资源 (原样发布不转码)
│   ├── assets/              # 番剧封面与媒资缓存
│   └── images/              # 博客图片与相册
│       └── albums/          # 摄影相册目录 (如 SampleAlbum/01.webp + info.json)
├── docs/                    # 内容仓结构说明与写作规范
├── .gitignore
├── README.md
└── shirone.content.json     # 内容仓库元数据（来源、挂载、保留与裁剪规则）

其中，这些是我们要用到的：

目录	用途
`/config`	编辑所有的配置表
`/content`	编辑文章、说说、系列与特殊页面的文案
`/data`	编辑特殊页面的内容
`/assets`	存放各种网站资产，图片、视频、音频等
`/.github`	编辑 GitHub 工作流，把网页部署到 GitHub Pages 时用到

在配置的过程中逐一熟悉即可。

工作流

以下是开发实践中总结的一些常用操作，由基本指令组合而成，详见快速开始 | 文档 | Shirone Docs 和 CLI 命令行工具链 | 文档 | Shirone Docs 。

调试：边改边看

在 /theme 下开两个终端，分别执行：

pnpm dev

pnpm content:watch

之后在浏览器打开 localhost:4321，每当外部编辑器修改了网站文件，就会触发局部热重载，网页刷新后显示更新后的版本。

拉取上游更新

分主题仓和内容仓两种情况。

主题仓：

git fetch upstream --tags
git merge upstream/main
# 重新安装依赖并检查
pnpm install
pnpm check

内容仓：

git fetch upstream --tags
# 检查是否存在冲突
git log --oneline HEAD..upstream/main
git merge upstream/main
# 同步内容更改
cd ..\blog
pnpm content:sync

::: caution[冲突处理]

如果在 merge 后出现了冲突，需要逐个 checkout 后再提交，最后同步内容更改。

建议交给 Agent 处理，分析了解情况后说明需求即可。

或者直接原地摆烂，放弃接收上游更新、固定模板版本，直接删掉主题仓和内容仓的上游分支：

git remote rm upstream

删之前先确定当前主题仓和内容仓同步到的最新版本是相同的，以免配置不匹配。

:::

推送更新

在内容仓目录下执行：

git add -A
git commit -m "本次更改概要"
git push origin main

如果需要提交主题仓的改动，请在 /theme 目录下执行（先清理构建期物化副本，避免把生成物提交进去）：

# 先清理主题仓中的临时副本
pnpm content:clean # 预演：打印清理计划
pnpm content:clean --yes # 实际执行清理
git add -A
git commit -m "本次更改概要"
git push origin main

配置调教：定制自己的网站

接下来，就可以在主题模板的基础上，更改配置项，制作属于自己的网站了。

由于配置中的个性化选项过多，且官方文档提供了详尽的引导，这里仅提供简略的指引，作为实操的参考。

::: info[文档阅读须知]

官方文档关于配置项的说明是面向单仓建站编写的，呈现的是主题仓中 .ts 文件的代码。但配置项是相同的，与内容仓中 .yaml 为一一对应的关系，请结合 README.md 理解。

:::

基本流程

编辑配置的方法十分简单，用 IDE 打开内容仓目录，然后在 blog-content/config 下找到你要改的配置项。例如我想要修改网页的标题，这一项在 site.yaml 中，于是我打开该文件，然后根据代码中的注释与官方文档中对应的说明，完成修改。

如果想即时确认修改结果，参见上文的边改边看。

配置顺序

下面是我编辑配置的顺序，可以作为实践参考。

修改建议说明：

必修：掌握每个配置项的用途并确认状态。
选修：依自身需求酌情配置，不想要可以关掉，一般是 enable: false。
开摆：没什么用或默认配置已经很完善了，想看看也行。

普通配置

配置项	配置文件	参考文档	修改建议
基础信息、配色、背景图等	`site.yaml`	基础配置、动态配色、横幅与背景	必修
博主资料	`profile.yaml`	页脚与博主资料	必修
顶部导航栏	`nav-bar.yaml`	导航栏配置	必修
左右侧栏	`sidebar.yaml`	侧栏布局、组件总览、基础组件	选修
公告栏	`announcement.yaml`	公告组件	选修
音乐播放器	`music.yaml`	音乐播放器、Meting API	选修
页脚	`footer.yaml`、`footer.html`	页脚与博主资料	开摆
字体	`font.yaml`	自定义字体	选修
文章页面	`article.yaml`	文章页配置	开摆
悬浮控制	`fab.yaml`	悬浮控制流（FAB）	开摆
右键菜单	`context-menu.yaml`	右键增强菜单	选修
版权声明	`license.yaml`	版权声明	选修
代码样式	`expressive-code.yaml`	代码块主题	选修
评论系统	`comment.yaml`	评论系统	选修
Umami 统计	`umami.yaml`	Umami 统计、Umami API	选修
AI 友好内容	`llms.yaml`	订阅与机器可读输出、LLM 友好内容	开摆
图片加载效果	`image-bloom.yaml`	图片色调辉光	开摆
全局永久链接	`permalink.yaml`	固定链接	开摆

独立页面配置

还有一些特殊的配置项，更改的是独立页面（归档、分类、关于等）的内容，它们除修改 .yaml 配置文件外可能还需要额外修改一些文件来写入页面内容，这里单列：

独立页面	配置文件	内容文件	参考文档	修改建议
关于	无	`content/spec/about.md`	关于页	必修
动态	无	`content/moments/`	瞬间页	选修
友链	无	`data/friends.ts`	友链页	必修
项目	`projects.yaml`	`data/projects.ts`	项目页	选修
技能	`skills.yaml`	`data/skills.ts`	技能页	选修
设备	`devices.yaml`	`data/devices.ts`	设备页	选修
游戏	`games.yaml`	`data/games.ts`	游戏页	选修
系列	`series.yaml`	`content/series/`	系列页	选修
时间线	`timeline.yaml`	`data/timeline.ts`	时间线	选修
追番	`anime.yaml`	无	番剧页、Bangumi API、Bilibili API、数据快照与离线同步	选修

独立页面较多，根据自身需求选用即可，没有必要全用。也可以先做一部分，等到有需求后再增加。

在 Shirone 写作

编辑配置表使其不断适配个性化需求的过程是令人上头的，但不要忘记博客网站最初的目的——博客网站一定要有博客。

Shirone 为 Markdown 提供了丰富的格式支持与特性扩展，与一种合乎逻辑的多文件夹组织方式。

用 Markdown 写作

官方文档提供了一份入门教程，基本覆盖了 Markdown 的常用语法，以供快速上手。此外，还有大量的富文本特性有待探索。在此之前，我们需要准备一个 Markdown 文本编辑器，这里推荐 Obsidian，原因如下：

强大的插件生态
较低的学习成本
天然支持 Frontmatter

::: info[Obsidian 使用教程]

编写并发布第一篇文章

以本文为例，首先在内容仓的博文目录下新建存放新文章的目录 /content/posts/site-building，然后在其下新建 site-building.md，并在文件开头填入：

---
title: 零基础搭建并装修精致优雅的二次元博客网站
permalink: site-building
published: 2026-10-24
publishedAt: 2026-10-24T14:25:41+08:00
description: 基于 Astro 框架 + Shirone 主题的静态博客建站方案，在官方文档的基础上补充了基于实践经验的整理与引导，以便上手和学习。
image: ./cover.png
tags:
  - 指南
  - 博客
category: 技术
draft: false
lang: zh-CN
---

这是博文的 Frontmatter，完整的配置项见 Frontmatter | 文档，这里只介绍重点：

:::: field-group

::: field permalink

@type string

@optional

文章的固定链接，如上填写则文章将固定在 网站地址/posts/site-building。

:::

::: field image

@type string

@optional

封面，如上填写，则会取同目录下的 cover.png 作为封面。

:::

::: field draft

@type boolean

@optional

是否为草稿，填 true 不会发布，填 false 则会发布。

:::

::::

详见编写文章 | 文档。

::: caution[不要动主题仓]

官方文档中提到的命令是针对单仓建站的，会在主题仓下生成文章文件：

pnpm new-post my-first-post

请保持双仓分离，一切内容创作在内容仓内完成。

:::

发个说说

上文提到的独立页面中，瞬间页相当于 QQ 空间，可用于发布一些轻量的内容，如随想、灵感、日常等。

要发布一条说说，只需在 content/moments 下新建 .md 文件，建议命名为 日期-标题，例如 2026-10-24-first-moment.md。然后填写说说的 Frontmatter：

---
published: 2026-10-24T21:30:00+08:00   # 发布时间（含时区），必填
mood: material-symbols:sentiment-excited-outline-rounded  # 心情图标
tags:                                   # 标签，用于筛选
  - 随想
images:                                 # 图片排版数组
  - src: /images/moments/arknights-7_5.webp
    alt: 《明日方舟》7.5周年活动
---
# 下为正文部分

这里 mood 使用了来自 materiail-symbols 的图标，目前 Shirone 支持 Iconify 图标库中的图标，默认安装的库有 fa7-brands、fa7-solid、material-symbols 和 simple-icons。

想使用图标时，可以到 Icônes 查找想用的图标并复制图标全名。

另外，说说的配图建议集中写在 Frontmatter 中，并将图片资产统一存放于内容仓的 /public/images/moments 下。

::: info[关于内容资产存放位置]

编辑页面内容时，可能会遇到不知道某个资产应该存放在哪个目录的情况，官方文档和注释也没有穷尽所有的细节。此时建议直接询问 Agent，让它梳理代码逻辑并告诉你文件位置。

:::

::: caution[图片资产]

图片建议先转换为体积较小的 .webp 格式再存放到相应目录中，尽管网站在构建过程中会自动压缩图片，过大的图片体积仍会占用仓库空间与延长加载时间。

一个在线转换图片格式的网站：在线图片转WebP格式工具

:::

各种特性

下面展示一部分 Shirone 支持的语法特性 +features。

GitHub 仓库卡片

::github{repo="LyraVoid/Shirone"}
::github{repo="LyraVoid/Shirone-Content"}

::github{repo="LyraVoid/Shirone"}

::github{repo="LyraVoid/Shirone-Content"}

嵌入 Bilibili 视频

::bilibili{bvid="BV1KKtV69E8a" title="主题宣传视频" p=1 preload="auto"}

::bilibili{bvid="BV1KKtV69E8a" title=" 演示视频 " p=1 preload="auto"}

折叠卡片

::: collapse accordion

:+ 默认展开的项目

这里是第一个卡片的内容正文。
默认折叠的项目

这里是第二个卡片的内容正文。

:::

部署网站

最后介绍如何将网站部署到不同的平台。

为此，我们需要准备：

一个域名（部署到 GitHub Pages 则不需要）
一台服务器或云服务（Vercel、EdgeOne、Netlify 等均提供适合个人静态博客的免费额度）
已托管的主题仓和内容仓

这部分操作详见官方文档中的部署部分，建议从本地构建看起。这里仅介绍我采用的 GitHub Pages 部署方式。

GitHub Pages 部署

1. 基础配置

我需要将网站部署到 https://tghyscifi.github.io，因此编辑 site.yaml：

site: "https://tghyscifi.github.io"
base: "/"

2. 配置 GitHub Actions

托管在 GitHub 的仓库只包含了源代码，我们需要告诉 GitHub 的云服务如何构建网站，因此需要编辑 GitHub Actions 工作流，内容仓与主题仓各一个。

内容仓

在 /blog-content/.github/workflows 下新建 trigger-build.yml：（参考 trigger-build.yml.example）

name: Trigger Theme Build

on:
  push:
    branches:
      - main
    paths:
      - "content/**"
      - "config/**"
      - "data/**"
      - "assets/**"
      - "public/**"
      - "shirone.content.json"
  workflow_dispatch: {}
  
concurrency:
  group: trigger-build
  cancel-in-progress: true
  
jobs:
  validate:
    uses: LyraVoid/Shirone/.github/workflows/content-validate.yml@main
    with:
      theme_repository: LyraVoid/Shirone
      theme_ref: main
      
  dispatch:
    needs: validate
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Dispatch build event to theme repository
        env:
          DISPATCH_TOKEN: ${{ secrets.DISPATCH_TOKEN }}
        if: ${{ env.DISPATCH_TOKEN != '' }}
        uses: peter-evans/repository-dispatch@v4
        with:
          token: ${{ env.DISPATCH_TOKEN }}
          repository: tghyscifi/tghyscifi.github.io # TODO: 使用者请替换为自己的主题代码仓
          event-type: content-updated
          client-payload: '{"sha": "${{ github.sha }}"}'

主题仓

在 /theme/.github/workflows 下新建 deploy.yml：(参考 deploy.yml.example)

name: Deploy

on:
  push:
    branches: [main]
    paths-ignore:
      - "docs/**"
      - "rules/**"
      - "README*.md"
      - "*.md"
  repository_dispatch:
    types: [content-updated]
  workflow_dispatch:
    inputs:
      content_ref:
        description: "内容仓 ref 或 commit SHA（留空使用 main）"
        required: false
        default: ""
  schedule:
    - cron: "17 4 * * *"
  
concurrency:
  group: deploy
  cancel-in-progress: true

permissions:
  contents: read
  pages: write
  id-token: write

env:
  CONTENT_REPOSITORY: tghyscifi/blog-content  # TODO: 替换为你的内容仓。
  CONTENT_WORKING_COPY: .content-src

jobs:
  deploy:
    name: Build and deploy
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    env:
      CI: true
      CONTENT_DIR: .content-src
      
    steps:
      - name: Resolve content ref
        id: target
        env:
          PAYLOAD_SHA: ${{ github.event.client_payload.sha }}
          INPUT_REF: ${{ github.event.inputs.content_ref }}
        run: |
          set -euo pipefail
          ref="${PAYLOAD_SHA:-}"
          [ -n "$ref" ] || ref="${INPUT_REF:-}"
          [ -n "$ref" ] || ref="main"
          echo "ref=$ref" >> "$GITHUB_OUTPUT"
          
      - name: Checkout theme
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        
      - name: Checkout content
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          repository: ${{ env.CONTENT_REPOSITORY }}
          ref: ${{ steps.target.outputs.ref }}
          path: ${{ env.CONTENT_WORKING_COPY }}
          token: ${{ secrets.CONTENT_REPO_TOKEN }}
          persist-credentials: false
          
      - name: Record content commit
        id: content
        run: |
          set -euo pipefail
          echo "sha=$(git -C '${{ env.CONTENT_WORKING_COPY }}' rev-parse HEAD)" >> "$GITHUB_OUTPUT"
          
      - name: Set up pnpm
        uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
        with:
          run_install: false
          
      - name: Set up Node.js
        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
        with:
          node-version: 22
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml
          
      - name: Restore build caches
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: |
            public/assets/moments/thumbnails
          key: ${{ runner.os }}-shirone-thumbnails-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-shirone-thumbnails-
            
      - name: Install dependencies
        run: pnpm install --frozen-lockfile --prefer-offline
        
      - name: Materialize content and config
        run: pnpm content:sync
        
      - name: Restore anime cache
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: |
            src/data/anime-snapshots
            public/assets/anime/covers
          key: ${{ runner.os }}-shirone-anime-${{ hashFiles('pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-shirone-anime-
            
      - name: Sync anime data (best effort)
        run: pnpm anime:sync --if-stale
        env:
          BILI_SESSDATA: ${{ secrets.BILI_SESSDATA }}
          
      - name: Build site
        run: pnpm build
        env:
          BILI_SESSDATA: ${{ secrets.BILI_SESSDATA }}
          
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist
          
      - name: Deploy to Pages
        id: deployment
        uses: actions/deploy-pages@v4
        
      - name: Summarize
        if: always()
        run: |
          set -euo pipefail
          {
            echo "### Shirone deploy"
            echo ""
            echo "- 内容仓：\`${CONTENT_REPOSITORY}\`"
            echo "- 内容 ref：\`${{ steps.target.outputs.ref }}\`"
            echo "- 内容 commit：\`${{ steps.content.outputs.sha }}\`"
            if [ -f content.lock.json ]; then
              echo ""
              echo "<details><summary>content.lock.json</summary>"
              echo ""
              echo '```json'
              cat content.lock.json
              echo '```'
              echo ""
              echo "</details>"
            fi
          } >> "$GITHUB_STEP_SUMMARY"

::: info[提示]

这里给出的代码只是最简版本，详细操作参见跨仓自动化构建与发布，完整代码为主题仓和内容仓下的两个工作流 .example。

:::

3. 编辑仓库设置

由于有两个仓库，跨仓构建要求两个仓库之间的通信，这就需要生成两个 GitHub PAT，点此直达：New Fine-grained Personal Access Token。

先生成一个 shirone-dispatch，选择一个有效期（建议 90 天并定期轮换，不建议设为永久），将 Repository access 设置为 Only select repositories，并选择主题仓，最后在 Repository permissions 下找到 Contents，设为 Read and write，点击生成后立刻复制下来。

再进入内容仓的 Setting 页面，在 Secrets and variables -> Actions 点击 New repository secret，密钥名为 DISPATCH_TOKEN，其值为刚才复制的内容。

填写完毕后，按相同的流程生成第二个 PAT，这次命名为 shirone-content-read，Only select repositories 选择内容仓，Repository permissions.Contents 改为 Read（只读即可）。之后在主题仓的密钥界面新建密钥 CONTENT_REPO_TOKEN，并粘贴密钥值。

两次操作总结如下：

PAT	`shirone-dispatch`	`shirone-content-read`
有效期	自定义	自定义
`Repository access`	`Only select repositories`	`Only select repositories`
选中仓库	主题仓	内容仓
`Repository permissions.Contents`	`Read and write`	`Read`
所在仓库	内容仓	主题仓
密钥名	`DISPATCH_TOKEN`	`CONTENT_REPO_TOKEN`

配置完成后，在主题仓库的 Setting 页，将 Pages->Source 改为 GitHub Actions 并保存。

之后，先推送主题仓，再推送内容仓，GitHub Actions 跑完后，网站就部署完毕了。

*[PAT]: 个人访问令牌

历史长夜中一道不合时宜的闪光——《闪光的哈萨维》中的左翼叙事及其当代启示

Mon, 31 Aug 2026 00:00:00 GMT

写在前面

那个寒冷的火星冬夜，一道流星曾短暂地撕开夜幕。也正是在这时，从新经济体制的劳动中抽离，麻木地扑向再生产的人们会久违地仰望深暗而压抑的夜空，将这一场景转录为社交网络中穿行的电波，畸变、演化、解构，最终消化为无意义的笑谈，沉积到无人问津的流量池底。这是一次机会主义的盲动，一场一厢情愿的殉道，一个军事贵族的自杀。它将迅速地被掩盖和遗忘，如幽灵般潜伏在历史的阴影里，直到三十年后，在一切都无可挽回之时，作为革命的普遍象征，被人们重新拾起。 ——《率月纪元》正传旧稿《1-1-B：弦外杂音》

这段文字是我在看完闪哈第一部后，在某种不可复现的心流下，为正传1-1-B（旧稿）写的开头。凛冬的故事几乎是哈萨维在率月纪元世界的翻版：军队建制出身，加入错误道路的革命组织，向政府高层发动恐袭，作为心理症结与矛盾象征的贵族少女，注定兵败身死的结局……不过，既称之为旧稿，正传1-1-B 的凛冬线显然是对富野由悠季原作的拙劣模仿，在此提及，也只是为了回顾当年初见闪哈的心境，与那些有待扬弃的纯粹的绮丽的暴烈的愿景。

闪哈 1 我前后看过不下八遍，这部作品对当时的我有种难以言喻的吸引力。建制内部生长出的反叛力量，对联邦高层直接的物理消灭，个体面对利维坦的无力感，明知路线错误仍然义无反顾，最终化身为 UC 漫漫长夜里的一道闪光……惋惜哈萨维命定的失败结局也好，批判马夫蒂脱离群众的错误路线也罢，闪哈 1 提供给迷茫时期的我的，远超故事本身。它几乎陪伴了我 25-26 年思想转变的整个历程：抚平那些对不公义人事的凶暴的躁动，代之以理性、克制、工程化的思维。前者依旧埋伏于胸中，间或受历史或时事的激发，后者则出现在落笔之后、行动之前，弥合冲动与现实间的鸿沟。

好了，我已经写了太多关于自己的话，是时候回到正题了。

UC0105：不合时宜的时代

写下这个标题后，我立刻意识到，“不合时宜的时代”这种说法本身就是不合时宜的。唯物史观的语境下，“时势造英雄还是英雄造时势”从来都不是可供争论的辩题。所谓“英雄”只是特定个体在特定时期被冠以的头衔，用以褒奖其在特定条件的特定超常表现或品质。静态地，以上所有“特定”均由时代环境提供；动态地，个体成为“英雄”前，乃至个体诞生前，时代的幕布已然铺就，为后续的一系列因果埋下伏笔。只是时代转折及其次生效应过于庞杂和震撼，而人们的记忆与注意力又极为有限，只能分配给关系网络中的少数核心人员，才有了英雄这种在回溯性建构中背负了时代的一切功业与罪责的身份。

因此，如果有人哀叹自己生不逢时，将失败归咎于时代的不合时宜，那么唯物史观给出的结论恰恰相反，是 ta 自命为英雄（而非追认），擅自活跃在历史舞台上，当了不合时宜的跳梁小丑。

对有志于肃清腐朽、再造人间的革命者来说，UC0105 就是这样一个不合时宜的时代。自地球向宇宙输出多余人口已过了一百年，此时大部分人都生活在太空殖民地，地球的环境问题也得到了一定缓解。然而，地球联邦政府一方面延续对殖民地人民的压迫，另一方面加紧对地球本地低端人口的清出。在自动化生产技术高度发达的背景下，底层人民大量沦为无用阶级，被排除在社会生产体系之外，可以被移民执法机构毫无顾忌地驱逐或屠戮。自 UC0079 的战乱以来，反联邦的各个势力均已溃败，战争中涌现出的理想主义者们或在历次战争中牺牲，或在阿克西斯的奇迹中献身，或在联邦体制内受打压排挤。需要革命来救治的病症，不幸地出现在了革命无法发生的时代。

这样的情况在历史上并不罕见，在当今世界也广泛存在着。在一些由反动政权统治的国家和地区，打着革命旗号的各色武装组织或是被无害化、被招安为利益网络的一环，或是演变为比他们所反对的更反动的东西。对他们加以否定与批判的同时，我们也应当反思：为什么当地只有这样的组织？那些我们认为的真正进步性的力量，为什么没能在那里诞生？是少数人的过失和无能，还是系统结构的自然产物？

UC0105 年，马夫蒂组织正式登上历史舞台。在闪哈第二部中，我们得以一窥该组织的风貌：成员多为非法移民和左翼青年，组织架构高度扁平化，日常氛围轻松融洽，革命态度积极乐观。的确有这样一群人，他们的生活被联邦夺走了，于是投身于推翻联邦这一远大志愿中，而他们的实践就是——发动恐袭，暗杀阁僚。通过对联邦这一官僚资本复合体的顶层代理人的物理杀灭，倒逼联邦实行改良政策，自内而外地覆变。

I've got to find, just find a better way Gonna wave against the wind Until the system changes from within Come with me (come with me) Together, we are strong (we are strong) And the way to get it done, get it done So that I don't have to feel, sorry ——Möbius - 泽野弘之

与其纠结该路线的合理性，不如回到马夫蒂组织的起源：代号“医生”的库瓦克·萨尔瓦将军（显然依旧是化名）在各地发展下线（其中之一便是哈萨维的导师），汇集人脉与军事资源，一手促成了马夫蒂的成立与壮大。仅就电影中的表现而言，马夫蒂的军备配置堪称豪华：一座藏在岛屿下的军事基地，一艘货运船，一艘航空飞机，四个 MS 战斗中队，一台最新锐高达。与之对应的是一种基于原作的黑暗解读：库瓦克·萨尔瓦将军其实是联邦在野党代表，刻意培植马夫蒂作为黑手套，铲除当权内阁官员，为自身上位铺垫。毕竟，现实中帝国主义国家资助恐怖组织的实例并不少见。现实政治的矛盾关系是盘根错节的，对新生的反抗力量而言，与敌人的一部分作暂时的利益勾兑是很常见的操作。然而，对于哈萨维时期的马夫蒂组织，我们已无法看到他们崛起后对在野党的清算了。

哈萨维：架上历史祭坛的伪卡里斯马

在高达系列中，存在着一种名为『新人类 (Newtype)』的特殊群体，常见于进入太空生活的宇宙移民，能力表现为异于常人的精神感应与预兆感知，即直觉、“第六感”、心灵感应这类常见于上世纪作品的要素。贯穿高达系列始终的一条暗线便是新人类的时代性悲剧：觉醒的新人类能够相互理解，却不得不在各自阵营服务于旧人类权贵的纷争。由于新人类驾驶 MS 的超人天赋与战争潜力，他们被各方势力利用并投入战争，甚至战争孤儿也被改造为具有精神缺陷的强化人。新人类与旧人类的矛盾，是地球 - 殖民地矛盾进一步发展的产物，深刻影响着人类的长远未来。

作为新人类的代表之一，夏亚·阿兹纳布尔在 UC 的角色是典型的卡里斯马——作为吉翁·戴肯之子及其政治遗产继承者，历次战争中为殖民地人民而战，凭借自身影响力就能于甘泉再造新吉翁。从政治家之子到流亡者，再从 MS 机师到总帅，他的一生正是新人类成为卡里斯马的标准模板。（由于其经历过于曲折复杂，这里只作片面的概述）

卡里斯马会让一个人的性格中拥有某种品质，借助这种品质，他能够脱颖而出，被当成天赋异禀、具有超自然、超人类，抑或极其罕见力量和品质的人。这些都是普通人所无法企及的，是源自神性或榜样的东西，在此基础上的个体就能成为领袖。 ——马克斯·韦伯

不同于传统型权威和法理型权威，卡里斯马的权威建立在领导者本人超凡的个人魅力与追随者的情感认同之上。从唯物史观的角度来看，情感认同更为重要。所谓个人魅力，也只是卡里斯马在特定历史时期，主动承载世人寄予的厚望，宣誓要代行民意的结果。对于持不同意见的人群，这种特质就会变成与魅力相对的某种极其恐怖的东西。当夏亚发动地球寒冷化作战时，他是殖民地人民拥护的卡里斯马，同时也是地球居民眼中的恶魔。

那么回到正题，哈萨维是卡里斯马吗？

哈萨维斗争的起点，是女友凯莉亚的非法移民身份。后来马夫蒂组织斗争的重心，也是联邦政府驱逐地球人口、让特权阶层独占地球的法案。他们提出的纲领，是让所有地球人口，无一例外地上太空。他们的实践，则是针对联邦高层的恐怖袭击，且多在市区进行。

虽然也有奥恩贝里军这种支持马夫蒂的存在，但在大部分地球民众眼里，马夫蒂是一伙“该死的恐怖分子”，是宣扬着过于渺远的理想的学问家，是为他们劳苦生活带来生命危险的暴徒。对本就生活在太空的殖民地人民，马夫蒂只是一个活跃在地球的，可以被粗浅理解为“夏亚再世”之类的遥远符号。

出租车司机：马夫蒂这人就是太有学问了。专挑大人物下手这点倒还好，不过说是最后大家要一起去宇宙吧？那个说法我就不明白了。达沃没有被污染得那么厉害吧？哈萨维：可是，绿化变少了，鱼也捕不到了吧？出租车司机：足够喂饱岛上的人了。哈萨维：马夫蒂说的似乎是一千年后的事。出租车司机：（大笑）那个人真是闲啊。所谓生活，是没有时间去考虑那么远的事情的。哈萨维：闲？出租车司机：不是吗？光是想着要获得地球居住许可证，得付给那些大人物多少钱，就没工夫考虑后天的事了。 ——《闪光的哈萨维 1》

因此，哈萨维并不是严格意义上的卡里斯马，而是在 UC0093 的战争中受到亡者的感召与牵引，在战后创伤与自毁倾向的引导下自立为卡里斯马，借着大义的名分宣泄自身的私情。这份私情在新人类的共感增幅下过于沉重，以至于他不得不从马夫蒂这一卡里斯马身份中寻求宏大叙事的超越性。当他戴上头盔、驾驶高达，名为哈萨维的个体暂时退场，米诺夫斯基飞行系统的反重力场将现实的重力屏蔽，只有马夫蒂，只有革命。

并非革命，而是表演革命。哈萨维内心清楚地知道，他的所作所为并不能为世界带来真正的公义，正如夏亚也厌恶着身穿总帅军服慷慨陈词的自己。联邦的腐朽让人痛恨，联邦的庞大则令人绝望。绝望之下，卡里斯马不接受妥协与绥靖，他们宁愿在错误的道路上奋战至死，不仅是因为他们是卡里斯马，更是由于他们的人生已被名为卡里斯马的皮套锚定，无法从民众的压力与自我的叩问中脱身。这正是哈萨维为自己选择的道路：在不合时宜的时代扮演卡里斯马，尝试以此救赎自己因战争破碎的心灵，最终走向命定的结局。

结局：闪光烁灭，丧钟长鸣

历史的惯性对个体而言太过漫长和痛苦。一个庞大帝国从衰落、崩解到毁灭往往要耗费以世代为单位的时间，大多数个体究其一生的夙愿也只是历史进程中的一个环节。哈萨维的人生完成的，正是 UC 历史长夜里的一道稍纵即逝的闪光。

夏亚和阿姆罗的时代已然落幕，两位传奇驾驶员的才能内耗在了阿克西斯的奇迹之中。事实证明，夏亚的军事冒险和阿姆罗的犬儒思想在 UC 无法生存。作为后继者的哈萨维，在夏亚和阿姆罗的基础上更进一步，把矛盾明确为联邦政府与底层人民之间的阶级矛盾，尽管路线仍有偏差，却也算是历史的进步。

革命从不是一蹴而就的。王朝末期，形形色色的组织揭竿而起，相继接过历史的接力棒。后人在历史书中看到的，只是最后一个组织探明了正确的道路，进而缔造了革命的最终胜利。可在那之前，革命大业得以落成的地基，是前面那些看似莽撞、愚痴的组织用一次次试错奠定的。可以说马夫蒂叛乱发生在了不合时宜的时代，可如果这个时代只能产生马夫蒂这样的组织，那么宏观地看待，马夫蒂作为过渡时期的反叛力量，反而是适宜的。闪光过后，终有回响。如果说见证了阿克西斯奇迹的少年哈萨维造就了马夫蒂的闪光，那么马夫蒂的闪光也终将启示后人，他们将继承马夫蒂的精神，扬弃马夫蒂的路线，把反抗联邦的旗帜接着打下去。所谓“人类的智慧”，并不是天生的禀赋，而是前人的勇气所激发的吧。

夏亚：地球是容不下人类全部的自私的！阿姆罗：（扭打）人类的智慧可以超越那种事！夏亚：那么你现在就赐予那些愚民们睿智给我看看吧！（翻滚） ——《逆袭的夏亚》

在历史上，总有这样一种无法避免的情况。一个强大的政权走向不可逆转的腐化变质，可距离下一次革命酝酿成熟还有五十年。这五十年在史书上是被一笔带过的“垃圾时间”，对先驱者们却是一生。他们将如何熬过这漫漫长夜？在大多数忙于生计而无暇顾及未来的人眼里，他们是不折不扣的异类、叛国者、危险分子。他们不得不同时面对依然强大的统治机器与尚未觉醒的“愚民们”，后者客观上充当了前者的或被动或主动的帮凶。他们最多能凑出的只有够完成几次暗杀行动的武装力量。所以，要干吗？作为生活在当下的历史主体，他们不知道后来的发展，更无从知晓自己在历史中的位置。或许，支撑他们行动的根本不是千秋功过这种宏大抽象的东西，而是他们个人的创伤经历和对苛政的仇怨。这些历史中不合时宜的暴乱，归根结底是系统内部矛盾的延伸，是帝国亲手种下的恶果。

写在黎明前的长夜

写到这里，已经很难称这篇文章为闪哈 2 观后感之类的东西，我甚至没有提及琪琪这个讲闪哈就绕不开的角色。大概，在我内心深处，闪哈的具体情节早已内化为某种更抽象的思考，而无法再被具体地讲述了。又或者，因为看了太多同类型的文章，我在组织论述时无法脱离其他人的范式，从而使写观后感显得多余了。总之，最后形成的，是这样一篇想到哪写到哪的杂谈集，或者说是我看完闪哈 2 后思绪状态的快照。

《闪光的哈萨维》是富野由悠季 1989 年的作品。书中的马夫蒂似乎是受了日本赤军组织的启发。近四十年后的今天，这部作品被改编为动画电影，却丝毫不显过时。现代军事体系营造的暴力壁垒，并不比高达与血肉之躯的差距小多少。AI 的发展势必加剧中产阶层的失业与无产化，甚至将无产阶级降格为无用阶级。与此同时，科技新贵们已经推出了黑暗启蒙主义这种极尽反动之能事的理论，为技术封建主义的到来作意识形态准备。我们的确有可能面对这样一幅绝望的未来图景：少数官僚和资本家掌控了暴力机器与生产资料，且树立了不可突破的技术壁垒，生产力空前发达却只向少数人分配，大多数人挣扎在贫困线上，向权贵变卖器官、尊严与人权维生。这听起来是在鼓吹末世论或阴谋论，可即便没有统治阶级有意促成这样的未来，他们也会极力扼杀任何剥夺他们特权的未来，从而使未来的可能性收束至上述样貌。这不是个人道德或思想倾向能决定的，而是阶级意识指向的必然结果。

在那之前，在历史的拐点于地平线上冒出可被众人辨认的明显征兆之前，保持观望是多数人的选择，而这是危险的。因为在当前的生产关系下，一旦科技的发展达到了某个阈值而人们依然放任科技被掌握在少数组织手中，那么这一分化就将被过于巨大的暴力与技术差距固定为不可逆的社会结构。到那时一切都太晚了，我们或许将见证真正的“历史的终结”，准确地说是“无产者的历史的终结”。因此，在那之前，必然有一连串行动作为颠覆这种悲剧性结构的总革命的预备。这种预备或许是马夫蒂式的亡命之徒的袭击，或许是列宁式的先锋队的联系，或许是互联网上的去中心化的社群，又或许是某种世所未见的先进的组织形式。无论如何，这种预备必须有人去做，它是无产阶级在新时代保有阶级自决权的唯一脆弱但有效的证明。