xiaobuhui

四篇的分工#

顺序就是推荐的上手顺序。

先认清一件事：你不是在搭站#

Shirone 是一个 Astro 7 站点，UI 用 Svelte 5，视觉体系是 Material 3 Expressive。这些都是优点，也正因为成熟，它上手反而偏慢：一个功能齐全的主题里，“能改的地方”和“改了有用的地方”是两回事。

它默认长这样：横幅大字写着 Shirone，副标题是五条日文短语，侧栏挂着作者的 GitHub，友链页是他收集的站，时间线上是他的里程碑。

改完是这样：上面所有地方都是你的。

中间有个很现实的问题：主题还在更新。你今天改的每一处，将来合并上游时都可能冲突。改得越少、越集中，将来合并越省事。

三层改造模型#

改造手段只有三种，风险从低到高。我把它当纪律用：能用上面一层的，绝不下下面一层。

结论先说：八成“想让它像我自己的”靠 L1 加 L2 就够了。真需要下 L3 的时候（比如我后来加的开场动画），一次做完，把改动登记下来，将来升级照着重新打一遍。

为什么要把仓库拆成两个#

这是整个改造里第一个、也是收益最大的决定。

主题默认是单仓：代码和内容躺在同一个目录里。结果就是，写一篇文章要打开代码编辑器，改个错别字会淹在一堆构建产物里。风险也不对等，手滑删了文章，跟手滑删了组件，性质完全不同。

双仓就是把它拆开：

两个仓并排放着就行：

1
E:\jisuanji\PycharmProjects\
2
├── Shirone\            # 代码仓
3
└── shirone-content\    # 内容仓

然后在代码仓根目录放一个清单文件，告诉构建内容在哪：

1
{
2
  "schemaVersion": 1,
3
  "source": {
4
    "type": "path",
5
    "path": "../shirone-content"
6
  }
7
}

有了它，pnpm dev 和 pnpm build 会先把内容仓物化到代码仓的 src/ 下，再开始构建。日常你只需要待在内容仓里写东西。

动手前先做两件事#

改造之前先给自己留一条退路。

第一，两个仓各建一个分支。

1
git checkout -b customize

L1 和 L2 的改动就算搞砸了，改回来也简单。但只要你动了 src/，没有分支就没法干净回退。

第二，给代码仓配上上游远端。

1
git remote add upstream https://github.com/LyraVoid/Shirone.git
2
git fetch upstream

fork 之后，origin 指向你自己的仓。没有 upstream，将来主题更新你没办法合并进来，只能重新 fork 一遍，或者手工复制文件。这一步花不了一分钟，但漏掉会很麻烦。

路线图#

改造我分成五段，按性价比排的：

有个顺序上的调整值得提一句。我原本打算先替换内容再调外观，实测之后反过来了。

原因有两个。一是外观配置不需要任何内容，改完马上能看到效果，正反馈来得快，适合在还很有干劲的时候做。二是删掉演示内容之后，主题自带的 Playwright 测试会大面积失败。那些测试直接断言了 /posts/admonitions/、/albums/AcgExample/ 这类具体演示资源。对个人站来说，那套测试本来也不是给你跑的（它是主题开发者用来验证主题的），但你要知道它为什么会红，别被吓到。

真正的验收标准其实是另外两个：astro check 不报错，加上浏览器里人工看。

小结#

这篇没有干货命令，但决定后面三篇的所有前提：

• 内容归内容仓，代码归代码仓，中间用一个 shirone.content.json 连起来
• 改任何东西之前，先想它在 L1、L2 还是 L3
• 动手前建分支、配 upstream

下一篇进入实操：怎么在不碰一行源码的前提下，把内容和外观全部换成自己的，包括横幅素材的具体规格。