xiaobuhui

改源码之前先问三个问题#

1. config/*.yaml 里是不是真的没有对应开关？先去代码仓的 src/config/README.md 翻一遍
2. 如果只差“一点点”，能不能用自定义 CSS 覆盖，而不是改原文件？
3. 改完之后，主题升级冲突了，我打算怎么合并？

第三个问题如果答不上来，先别改。这也是我把每次改动都记下来的原因。

一个必须知道的规矩：两处要同步#

代码仓里有两个地方都定义了集成配置：

• astro.config.mjs：构建时实际生效的那份
• src/integration/index.ts：npm 包 shirones 的镜像

主题同时以“源码项目”和“npm 包”两种形态发布，所以改了其中一处，另一处也要同步。只改一处的话，dev 看着是好的，发布成包之后就丢配置了。

我就因为这个多花了一轮排查。

开场动画#

这是整个改造里投入最大的一块，前后两天。

起因很简单：看到一个参考站的开屏效果不错，想让自己的站也有。拆解之后发现实现不复杂，就是纯 CSS @keyframes 加一个 class 状态机，没有 Canvas、没有 WebGL，也不用引入 GSAP 那种动画库。

1
src/types/openingAnimationConfig.ts     # 类型
2
src/config/openingAnimationConfig.ts    # 配置，默认 enable: false
3
src/utils/opening-animation.ts          # 会话标记等纯逻辑
4
src/components/organisms/OpeningCinema.astro   # 组件本体
5
src/layouts/Layout.astro                # 插两行

角色装饰带#

参考站流行在页面底部摆一排角色立绘。我在两个地方各摆了一排：页脚和首页横幅底部。

页脚那排可以纯配置搞定：页脚支持注入一段 HTML，把 8 张图贴进去就行，不碰组件源码。

首页横幅那排不行。横幅是纯源码组件，没有页脚那种注入槽，也没有“往横幅塞装饰”的配置项，只能改 src/components/organisms/BannerStage.astro，加一个新图层。

1
.banner-stage__characters img {
2
  height: var(--strip-h);
3
  flex: 0 1 auto;
4
  min-width: 0;
5
  object-fit: contain;
6
  object-position: 50% 100%;
7
}

友链申请页#

需求是：友链页标题右边加一个按钮，点进去是一个独立的申请页，告诉别人怎么加我。

这一页有个让人意外的好消息：主题给每个代码块内置了复制按钮。所以整页只需要一份 Markdown，照样有“点一下复制”的体验，一行组件代码都不用写。

代价是纯 Markdown 只能单列流式排，做不出参考站那种左右两栏。我的判断是阅读顺序反而更顺，就接受了。

实现上照着主题已有的占位页写一个 src/pages/friends/apply.astro：从内容仓读一份 md、渲染进卡片里，标题取正文的一级标题，页面代码里零硬编码文案。

三个细节：

• 对外公示的头像要另存一份到 public/。assets/ 下的图走图像管线，产物 URL 带 hash，换头像 URL 就变，别人早就复制走的链接会失效。public/ 下文件名固定，换头像覆盖同名文件即可。
• 加国际化文案必须 10 个语言全加。那张表是穷尽类型，缺一个就编译报错。
• 标题栏没有预留按钮位，而且被十几个组件共用。我没去改它，而是把标题和按钮包进一个 flex 容器，样式上用 :global() 穿透 Svelte 的作用域。

图标系统：一条最值钱的坑#

这条如果不知道，能白排查一整天。

主题的图标是离线内联的，构建时从一个本地图标集合里取，运行时不联网。负责生成这个集合的脚本只扫 src/ 下六种扩展名：.astro、.md、.mdx、.svelte、.ts、.tsx。

.yaml 不在里面。

所以你在 config/*.yaml 里写一个从没用过的图标名，结果是：图标空白，零报错，零警告。构建成功，页面正常，就是那块地方什么都没有。

解法是在内容仓建一个 data/custom-icons.ts，把要用的图标按 "图标集:图标名" 的格式带前缀登记进去。这个文件在 src/ 下，会被扫到。

顺序也别错：

1
# 改 YAML → 同步 → 重新生成图标
2
pnpm content:sync
3
pnpm icons:generate

这一轮改完，记得登记#

我维护了一张改动登记表，每改一处填一行：日期、文件、改了什么、为什么配置做不到、升级冲突风险。

看着麻烦，但主题更新的时候它就是救命的东西，你不用去 diff 整个 src/，照着表把这几处重新打一遍即可。

小结#

这一篇的四件事，按“要不要动”排序的话：

下一篇是最后一篇，把这堆东西从本地推到线上：构建链路、GitHub Actions、服务器和域名。