Xieluyang

博客更新日志：从 Spaceship 买域名，到 007912.xyz 能打开

Sun, 27 Sep 2026 00:00:00 GMT

</div>

这个站现在可以通过 https://007912.xyz 访问了。这一篇把从买域名到真正能打开的全过程记下来 —— 前面是步骤，最后是踩到的两个坑，其中一个把评论区清空了。

为什么要买域名

在此之前站点一直挂在默认地址上，形如 xieluyang912.github.io/fuwari/。能用，但有几个别扭的地方：

分享出去的链接又长又像一串编号，看着不像个正经站点
以后要是换个托管（比如从 GitHub Pages 挪到别的静态托管），地址就全变了
域名是自己的东西，托管商可以换，域名不用换

所以决定自己买一个。

一、在 Spaceship 下单

Spaceship 是 Namecheap 团队做的注册商，界面比传统注册商干净一些。它有个好处是域名自带免费的 Basic DNS 和 Whois 隐私保护 —— 这两样在别家经常要单独加钱或者单独开开关。

流程本身没什么特别的：

打开 https://www.spaceship.com，在搜索框里输入想要的域名
列表里显示能不能注册、首年多少钱
加入购物车，选注册年限（最少 1 年）
结账：填邮箱、注册账号、付款

:::note[下单前先看一眼续费价] .xyz 这类后缀首年经常便宜得离谱，续费价却是另一个数量级。结账页一般会写明续费多少钱，介意的话就把年限一次买长一点，或者记下来明年提前比价。 :::

买完之后进入域名的 Manage 页面，有两个开关值得确认一下：

Auto-renew（自动续费）：建议打开。域名过期被释放之后，赎回价通常是注册价的几十倍，还可能已经被别人抢注了。
Whois privacy（隐私保护）：Spaceship 对多数后缀是默认送的，确认它是开着的 —— 不然你的姓名、邮箱、电话会直接暴露在 whois 查询里。

二、加解析记录，把域名指向 GitHub Pages

GitHub Pages 对外服务的 IP 是固定的。根域名要用 A 记录（IPv4）和 AAAA 记录（IPv6）指过去，www 用一条 CNAME 指到默认域名。

在 Spaceship 的域名管理页找到 DNS（有的地方叫 Advanced DNS），照下面的表加：

类型	主机	值	TTL
A	@	185.199.108.153	自动
A	@	185.199.109.153	自动
A	@	185.199.110.153	自动
A	@	185.199.111.153	自动
AAAA	@	2606:50c0:8000::153	自动
AAAA	@	2606:50c0:8001::153	自动
AAAA	@	2606:50c0:8002::153	自动
AAAA	@	2606:50c0:8003::153	自动
CNAME	www	xieluyang912.github.io	自动

几个容易写错的地方：

主机名只填「这一段」。根域名那一栏填 @ 或者留空，www 就只写 www，不要把整个域名再写一遍 —— 写成 www.007912.xyz.007912.xyz 是很常见的低级错误。
CNAME 的值不带仓库名、不带斜杠、末尾不加点。是 xieluyang912.github.io，不是 xieluyang912.github.io/fuwari。
根域名不能用 CNAME。DNS 规范不允许根域出现 CNAME，所以根域老老实实用 A / AAAA。
AAAA 那四条是 IPv6，不是必须的，加上没坏处。
如果域名刚买，面板里可能已经有一套默认的 parking 记录，注意别和自己的记录打架。

改完要等它生效，通常几分钟，慢的话几小时，取决于 TTL 和各地 DNS 缓存的脾气。

三、在 GitHub Pages 里绑定域名

进仓库的 Settings → Pages：

Build and deployment → Source 选 GitHub Actions。本站的 .github/workflows/deploy.yml 就是按这个前提写的，选错了部署步骤会直接报错。
Custom domain 填 007912.xyz —— 只填域名，不要带 https://，也不要带路径 —— 然后 Save。
等 GitHub 做 DNS check。它会去查你刚加的那几条 A 记录；没生效就会提示 DNS check unsuccessful，不用慌，过一会儿再点一次就行。
check 通过之后，Enforce HTTPS 的勾才能真正点上。证书由 GitHub 自动签发，一般几分钟到十几分钟，偶尔要等到 24 小时 —— 在这之前 https 打不开是正常的。

:::note[为什么要在 public/ 里放一份 CNAME] 用「分支 + 目录」的方式发布时，GitHub 会往仓库里写一个 CNAME 文件来记住自定义域名。但本站是用 Actions 发布构建产物的，没有那个分支，GitHub 没地方写 —— 所以要自己在 public/CNAME 里放一份，构建时会被原样复制到 dist 根目录。

这份文件一旦丢了，自定义域名的设置会被重置，站点就退回默认地址了。 :::

四、改站点自己的配置

域名换掉之后，站点里有两处必须跟着改，否则站点能打开、但生成出来的链接还是旧的：

// astro.config.mjs
site: "https://007912.xyz",  // sitemap、RSS、OG 标签用的绝对地址
base: "/",                   // 绑定自定义域名后站点位于根路径

# public/CNAME
007912.xyz

site 影响的是构建时生成的绝对链接：sitemap.xml、RSS 里的文章地址、分享到社交平台时的 OG 卡片。忘了改的话，页面本身没事，但搜索引擎和 RSS 阅读器拿到的还是老地址。

base 则是路径前缀。绑了自定义域名，站点就在根路径上，所以是 /。（哪天想改回用默认地址访问，这里要改回 /fuwari/，同时删掉 public/CNAME。）

踩到的两个坑

1. base 一改，评论区全空了

这是这次最难受的一个。

换域名之后，所有旧文章底部的评论都不见了 —— 去 GitHub Discussions 里看，评论还在，页面上就是不显示。

原因是评论用的 giscus 按 pathname 匹配 discussion：

换域名前：https://xieluyang912.github.io/fuwari/posts/hello-world/
换域名后：https://007912.xyz/posts/hello-world/

base 从 /fuwari/ 变成 /，页面路径整体短了一截，giscus 拿着新路径去 Discussions 里找，自然对不上任何一条。

已经产生的评论不会自动迁移。根治的办法是换一种匹配方式：把 giscus 的 mapping 从 pathname 改成 og:title，改成按文章标题匹配。这样评论就和域名、路径彻底解耦，以后再换域名也不会丢。代价是文章标题不能随便改。

2. Enforce HTTPS 一直点不动

绑完域名去勾 HTTPS，发现那个框是灰的、点不了。

这不是出错了，是顺序问题：GitHub 得先确认域名确实解析到了它、再签发证书，然后「强制 HTTPS」才可用。等的期间可以先自己验证一下解析通没通：

nslookup 007912.xyz
# 或者直接看响应头
curl -I http://007912.xyz

如果 nslookup 查不到或者还返回旧 IP，先清一下本机 DNS 缓存（Windows 上是 ipconfig /flushdns），再等一会儿。

最后

顺带记一句：域名解析到 GitHub Pages 这种境外托管，是不需要 ICP 备案的 —— 备案针对的是放在国内服务器上的站点。代价是国内访问的速度和稳定性看运气，这个只能自己权衡。

现在站点在 https://007912.xyz；绑定自定义域名后，原来的默认地址也会跳转到新域名。如果你发现有哪里还是老链接、或者某篇文章的评论对不上，欢迎在下面说一声。

博客更新日志：给页脚加上 CC 许可声明

Sun, 27 Sep 2026 00:00:00 GMT

</div>

这篇文章记录三件事：为什么选这个协议、代码写在哪个文件、以及实现时踩到的两个坑。

声明长什么样

页脚最下面那行就是，结构是标准的 CC 署名格式：

xieluyang' blog © 2026 by xieluayng is licensed under Creative Commons Attribution-NonCommercial 4.0 International [cc] [by] [nc]

这是 Creative Commons 官方推荐的排版方式，由五段组成：

部分	内容	作用
作品名	xieluyang' blog	哪件作品被授权
年份	2026	版权起始年份
作者	xieluayng	版权归谁
协议名	CC BY-NC 4.0	用哪个协议
协议图标	cc / by / nc	协议条款的可视化缩写

为什么是 CC BY-NC 4.0

Creative Commons 的协议是「模块拼装」出来的，四个模块两两组合，得到六种常用协议。本站选的这两个模块是：

缩写	全称	含义	本站
BY	Attribution	转载必须署名原作者	✅ 保留
NC	NonCommercial	不得用于商业用途	✅ 保留
SA	ShareAlike	衍生作品必须用同样的协议	❌ 未选
ND	NoDerivatives	不允许修改后发布	❌ 未选

另外两个模块没选，是有意的：

没选 SA：SA 要求「你改了再发，也得用 CC BY-NC 4.0」。听起来很美好，但实际会造成协议传染 —— 别人引一段代码进自己的项目，可能整套项目都被要求跟着换协议。对技术博客来说太麻烦。
没选 ND：ND 禁止修改。但博客文章被摘录、被翻译、被节选，绝大多数情况下是合理的引用行为，一刀切禁掉反而拦住了正常的传播。

所以 BY-NC 这个组合的含义可以一句话概括：

欢迎转载和引用，署名就行，但别拿去做生意。

它管不着什么

有两点必须说清楚，否则这行声明容易给人错误的预期：

:::warning[CC 协议不覆盖代码] 文章里的代码片段，严格来说不属于「文学艺术作品」，CC 协议对它并不是最合适的授权工具。正经做法是代码用 MIT 或 Apache 之类的软件协议单独声明 —— 本站代码本来就是从 Fuwari（MIT）改来的，沿用原协议即可。

页脚这行声明，主要覆盖的是文章正文。 :::

:::note[NC 只约束别人，不约束自己] 「非商业性使用」限制的是被授权方。也就是说：别人不能拿本站内容去卖钱，但我自己保留一切权利 —— 想出书、想接广告、想授权给商业机构，都不受这行声明影响。

版权始终在自己手里，CC 协议是「预先给出的许可」，不是「放弃版权」。 :::

代码写在哪

全部改动集中在一个文件：src/components/Footer.astro 的第 21–30 行，也就是原来 "Powered by Astro & Fuwari" 那行的下面、同一个圆角容器内部。

新增的是一个和上面那行同样式的 <div>：

<div class="transition text-50 text-sm text-center mt-2">
    <a class="transition link text-[var(--primary)] font-medium" target="_blank"
       href="https://xieluyang912.github.io/fuwari/">xieluyang' blog</a>
    &copy; {currentYear} by
    <a class="transition link text-[var(--primary)] font-medium" target="_blank"
       href="https://github.com/xieluyang912">xieluayng</a>
    is licensed under
    <a class="transition link text-[var(--primary)] font-medium" target="_blank"
       href="https://creativecommons.org/licenses/by-nc/4.0/">Creative Commons Attribution-NonCommercial 4.0 International</a>
    <img class="dark:invert" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt="" style="...">
    <img class="dark:invert" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt="" style="...">
    <img class="dark:invert" src="https://mirrors.creativecommons.org/presskit/icons/nc.svg" alt="" style="...">
</div>

几个设计上的选择：

类名照抄上面那一行（text-50 text-sm text-center），视觉上两行才是同一套语言，字号颜色自动跟着主题变量走。
mt-2 拉开和 "Powered by" 的间距，否则两行贴在一起像一句话。
年份用 {currentYear} 而不是写死 2026：文件顶部本来就有一行 const currentYear = new Date().getFullYear()，上面版权行也用它。跟着用，以后不用每年手动改。

:::note[关于 id="license-year"] 初版我给年份 span 加了个 id="license-year"，想的是以后用 JS 更新。但翻了一遍源码，全站没有任何脚本引用它 —— 上面那行的 id="copyright-year" 同样是个没人用的空壳，年份其实是构建时就算好的。

既然是静态构建，直接写 {currentYear} 就够了，多出来的 id 只是噪音，已删。 :::

两个必须处理的细节

直接照抄官方给的 HTML 片段，会坏在两点上：

1. 暗色模式下图标会消失

mirrors.creativecommons.org 上的三个图标是纯黑色的 SVG。

本站有暗色主题，页脚在暗色下背景接近黑 —— 黑图标放在黑底上，等于没有。这不是「有点淡」，是彻底看不见。

解决办法是 Tailwind 的 invert 工具类，配合本站的暗色变体：

<img class="dark:invert" src="...cc.svg" ...>

dark:invert 只在 <html> 挂上 dark 类时生效，把黑色反成白色。浅色模式下原样不动。

2. 图标会比文字低一截

官方片段只给了 max-width 和 max-height：

style="max-width: 1em;max-height:1em;margin-left: .2em;"

<img> 默认是 display: inline，参与文字基线对齐 —— 图标的底边会对齐到文字基线，视觉上就是整体往下沉了一截，和旁边的字不在一条线上。

补两个属性即可：

display:inline-block; vertical-align:middle;

:::warning[这两个坑不止 CC 图标会遇到] 远程 SVG 图标 + 有暗色主题 + 行内跟随文字 —— 这个组合都会翻车。以后往正文或页脚塞任何外部图标，先检查这两点。 :::

图标从哪来

三个图标走的是 Creative Commons 官方的 presskit 镜像，这是 CC 官方提供的标准素材地址：

https://mirrors.creativecommons.org/presskit/icons/cc.svg   # CC 标志
https://mirrors.creativecommons.org/presskit/icons/by.svg   # 署名
https://mirrors.creativecommons.org/presskit/icons/nc.svg   # 非商业

用哪个协议就挂哪几个图标。比如选了 BY-SA，就把 nc.svg 换成 sa.svg；选了 CC0，只挂 cc.svg 和 zero.svg。

另外推荐在页面里也放上协议全文的链接（就是那行 "Creative Commons Attribution-NonCommercial 4.0 International" 上的超链接），指向 https://creativecommons.org/licenses/by-nc/4.0/。CC 官方建议图标 + 协议名 + 链接三者齐全，只放图标容易被误解成别的协议。

:::note[图标是远程加载的] 和徽章那篇里说的一样：这些 SVG 是访客浏览器直接向 mirrors.creativecommons.org 请求的，构建时不会下载。

好处是离线也能构建成功；代价是网络不通时那三个位置会空着 —— 因为 alt=""，连替代文字都没有。这是刻意的：图标只是协议名的视觉补充，旁边的文字已经把授权说清楚了，图标缺失不影响法律效力。 :::

以后要改什么

想改	改哪里
换协议	改协议名文字、链接地址、图标文件名（三处都要动）
改署名	改 "xieluayng" 那几个字和它指向的链接
改年份	不用改，`{currentYear}` 每年自动更新
改博客名	改 "xieluyang' blog" 和它指向的链接
整行删掉	删 `Footer.astro` 第 21–30 行那个 `<div>`，其余不动

:::warning[换协议时最容易漏的一处] 三个图标是手写的三个 <img>，不是循环生成的。从 BY-NC 换成 BY-SA 时，很容易只改协议名和链接、忘了把 nc.svg 换成 sa.svg —— 结果声明写的是 SA，图标画的是 NC，两者矛盾。

协议名、链接、图标，三处必须一致。 :::

这行声明没能覆盖的

写在这里免得以后自己忘了：

代码片段：如前所述，CC 对代码不是合适的工具，本站代码实际跟着上游 Fuwari 走 MIT。
封面图和正文配图：本站图片多来自 Pexels 等免费图库。图库图片的版权不在我手里，我无权把它们纳入 CC BY-NC 授权。如果将来有人完整转载文章，图片的授权问题需要单独说明。
访客评论：评论存在 GitHub Discussions，版权归评论者本人。

所以更准确的说法是：这行声明覆盖的是「除特别注明外」的原创文章正文。

加许可声明的检查清单

[ ] 协议选好了：BY 必选，NC / SA / ND 按需组合
[ ] 协议名、链接地址、图标文件三者一致
[ ] 图标加了 dark:invert（有暗色主题的话）
[ ] 图标加了 display:inline-block; vertical-align:middle;
[ ] 年份用 {currentYear}，别写死
[ ] 署名和链接指向的是自己
[ ] 想清楚这行声明的边界：代码？配图？评论？

最后

改完之后我重新构建了一遍，确认 example.com 这个占位地址在产物里已经归零、三个图标和协议链接都正常出现在页面上。

有点讽刺的是，写这篇文章的过程本身就在提醒自己：许可声明不是加一行字就完事，它逼着人把「哪些东西是我的、哪些不是我的」想清楚。配图那一块就是我这次才意识到的漏洞，以后有空再单独处理。

博客更新日志：文章顶部的徽章标签怎么用

Sun, 27 Sep 2026 00:00:00 GMT

</div>

上面这一排就是这篇笔记要讲的东西。它出现在本站大多数文章的正文最前面，作用是在读者还没开始读之前，先把「讲的是什么、属于哪个方向、用什么做的」交代完。

以后给新文章加一排，照抄下面的模板改文字就行。本文记录它的三个组成部分、地址怎么拼、本站的配色约定，以及几个踩过的坑。

其实是三样东西拼起来的

一排徽章由三个部件组成，缺一个都不成立：

部件	位置	作用
徽章图片	`https://img.shields.io/badge/...`	真正的「标签」，由 shields.io 按 URL 现场生成 SVG
容器	Markdown 里的 `<div class="badge-row">`	把这一排圈起来，交给下面的 CSS 排版
样式	`src/layouts/Layout.astro` 的 `<style is:global>`（约 197–211 行）	排成一行、放不下自动折行、清零图片外边距

:::note[为什么样式写在 Layout.astro 里] Markdown 正文是构建时才拼进页面的，Astro 的组件级 scoped 样式管不到它，所以 .badge-row 的规则必须放在 <style is:global> 里。反过来说：改那一小段会影响全站所有文章的徽章，动手前先想清楚。 :::

最小可用示例

把下面这段贴进文章正文就能用：

<div class="badge-row">

![Static Badge](https://img.shields.io/badge/qq-234259867-blue?logo=qq)
![Static Badge](https://img.shields.io/badge/github-xieluyang912-orange?logo=github)
![Static Badge](https://img.shields.io/badge/pnpm-%3E%3D9-green?logo=pnpm)

</div>

渲染出来是这样：

</div>

shields.io 的地址怎么拼

固定格式是三段，用 - 连接：

https://img.shields.io/badge/<标签>-<内容>-<颜色>

标签（左半，可选）：这一枚在说什么，例如 pnpm、项目
内容（右半）：具体值，例如 >=9、大创
颜色：命名色或十六进制，控制右半的背景色

只有「内容 + 颜色」也合法，会渲染成单段徽章，例如 https://img.shields.io/badge/just%20the%20message-8A2BE2。

转义规则（最容易出错的地方）

因为 - 被用来分隔字段，所以文字里的特殊字符必须先转义：

想显示	要写成	说明
空格	`_` 或 `%20`	两种都认，`%20` 更不容易和下面的规则打架
下划线 `_`	`__`	单个 `_` 会被当成空格
连字符 `-`	`--`	单个 `-` 是字段分隔符，直接写会被拆开
中文	百分号编码	例如 `支持库` → `%E6%94%AF%E6%8C%81%E5%BA%93`
`#`	`%23`	十六进制颜色必须这么写，否则会被当成页内锚点
`%`	`%25`	例如 `95%` → `95%25`
`/`	`%2F`	路径里直接写 `/` 会被当成新的路径段

连字符这条最坑，看对比（上面是直接写，下面是转义后）：

</div>

claude-code-orange 会被拆成「标签 claude + 内容 code + 颜色 orange」三段，想显示 claude-code 必须写成 claude--code。

可选参数

在地址后面用 ? 接查询参数，多个用 & 连接：

参数	作用	例子
`style`	徽章形状	`?style=flat-square`（还有 `plastic`、`for-the-badge`、`social`，默认 `flat`）
`logo`	左侧图标，填 simple-icons 的 slug	`?logo=astro`
`logoColor`	图标颜色	`?logoColor=white`
`labelColor`	左半部分的背景色	`?labelColor=grey`
`label` / `color`	覆盖路径里写的标签 / 颜色	`?label=healthiness`
`link`	给左右两半分别挂链接，只在 `<object>` 标签里生效，`<img>` 无效	——

想让徽章可以点击跳转，别指望 link，用 Markdown 链接把图片包起来即可：

[![Static Badge](https://img.shields.io/badge/qq-234259867-blue?logo=qq)](https://qm.qq.com/q/xxxxxx)

本站的配色约定

颜色不是随便挑的，同一含义尽量用同一个颜色，翻文章时才有一致的观感：

颜色	本站用途	现有例子
`blue`	身份、账号、归属	`qq`、`github`、`steam`、`zotero`、`归属-网站维护`
`green`	工具链、技术、版本	`pnpm`、`nodedotjs`、`支持库-astro`
`orange`	项目、主题、场景	`项目-大创`、`场次-2026.09.26 苏州`
`red`	关键值或强调	`nodedotjs >=20`、`歌手-黄霄雲`
`yellow`	不刺眼的点缀	`counterstrike`
`lightgrey`	草稿、占位、说明	`状态-草稿`

可用的颜色有两类：

shields 自带的命名色：brightgreen、green、yellow、yellowgreen、orange、red、blue、grey、lightgrey
任意 CSS 颜色：purple、pink 这类颜色名，或十六进制（注意 # 要写成 %23，例如 %23ff69b4）

:::warning[颜色名拼错不会报错] 写错颜色名时 shields 不会提示，而是静默回退成默认的亮绿 brightgreen。本站早期几排徽章里的「支持库-astro」写的是 yello（少了一个 w），渲染出来一直是绿色而不是黄色 —— 这次一并改成了 yellow。同理，logo 的 slug 写错也不报错，只是图标不显示。 :::

图标从哪来

logo 参数的值是 simple-icons 的 slug：打开官网点图标标题就能复制，或者直接查仓库里的 slugs.md。

不确定某个 slug 存不存在，可以先探活：

https://cdn.simpleicons.org/<slug>     # 200 = 有，404 = 没有

本站用到的几个：qq、wechat、github、steam、zotero、applemusic、counterstrike、ea、500px、ubisoft、pnpm、nodedotjs、astro、markdown、pubmed、claude、deepseek、shieldsdotio。

排版上的两个注意点

同一段落里换行，中间不要空行。 Markdown 里连续几行属于同一个 <p>，.badge-row > p 才能把它们排成一行；中间插了空行就会被拆成多个 <p>，一个 <p> 占一行。
<div> 标签那两行留空行没问题，本站惯例是 <div class="badge-row"> 后空一行、徽章写在一起、再空一行写 </div>。

至于为什么必须套 badge-row：prose 默认给图片上下各 2em 外边距，一排徽章直接写会被撑出很大的空隙；badge-row 把 margin 清零，改用 gap 统一控制行内与行间距，窗口变窄时自动折行。

中文一键转义

手抄百分号编码太容易错，直接用现成的函数：

# PowerShell：得到 %E6%94%AF%E6%8C%81%E5%BA%93
[uri]::EscapeDataString('支持库')

// Node / 浏览器控制台：同样得到 %E6%94%AF%E6%8C%81%E5%BA%93
encodeURIComponent('支持库')

两个函数都不会转义 -，所以内容里真的要写连字符时，仍然要自己补成 --。

加一排徽章的检查清单

[ ] 先想清楚这一排要表达什么：身份？主题？版本？状态？
[ ] 一行一枚徽章，中间不空行
[ ] 中文和特殊字符都转义过了
[ ] 颜色名是合法值（别写 yello）
[ ] logo 的 slug 用 cdn.simpleicons.org 探过
[ ] 整排包在 <div class="badge-row"> 里

本站现有徽章一览

文件	徽章主题	数量
`src/content/posts/hello-world.md`	联系方式 + 技术栈	9
`src/content/posts/beiwanglu.md`	联系方式 + 技术栈 + 常用软件	13
`src/content/posts/giscus.md`	联系方式 + 技术栈	9
`src/content/posts/xmjs.md`	联系方式 + 技术栈 + 常用软件	13
`src/content/spec/about.md`	联系方式 + 技术栈 + 摄影 / 游戏	11
`src/content/posts/1.md`	大创项目：学科、人群、技术路线	7
`src/content/posts/2.md`	大创项目：申报书用途、方法、文献库	6
`src/content/posts/huangxiaoyun-live.md`	演出信息：歌手、巡演、场次、曲目	5
`src/content/posts/tuki.md`	图库索引：数量、用途、状态	5

后四篇原来没有徽章，是 2026-09-27 按本文的约定补上的：学习类文章用「项目 / 学科 / 人群 / 技术」这类中性字段，生活类文章用「歌手 / 巡演 / 场次 / 曲目」，草稿统一挂一枚 状态-草稿 作提示。

几个坑速查

单个 - 是字段分隔符，文字里的连字符要写 --
颜色名拼错会静默变成亮绿，不报错
logo slug 拼错不报错，只是没有图标
徽章是访客浏览器直接向 img.shields.io 请求的远程图片，构建时不会下载 —— 所以离线也能构建成功，但网络不通时页面上只剩 alt 文字
图片 alt 统一写 Static Badge，和 shields 官方示例保持一致，方便一眼搜出全站所有徽章

博客更新日志：照着 mizuki.mysqil.com 把整站版式重排了一遍

Sun, 27 Sep 2026 00:00:00 GMT

</div>

之前给博客加了看板娘、右侧栏统计、日历、音乐播放器这些功能，功能是齐了，但版式还是 Fuwari 原来的样子——页面 75rem 宽、两栏、导航栏是一张不透明的卡片、文章卡片的信息挤在底部一行小字里。

这次的目标很直接：照着 https://mizuki.mysqil.com/ 把整站的排版重做一遍。参考站是 Mizuki 主题的官方演示站，和本站同源（都从 Fuwari 长出来），所以「抄」起来阻力最小。

本文记录改了哪些东西、怎么确定改对了，以及几个不报错但静默失效的坑——那几个才是真正花时间的部分。

一、先学会「量」，再动手改

照着别人的站改版式，最大的风险是「我觉得像了」。肉眼看两张截图很容易自我欺骗，所以这次全程靠数字说话，分三步。

1. 把参考站截下来

用无头 Edge 直接截图，桌面端、长图、深浅色各来一张：

& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --headless --disable-gpu --hide-scrollbars `
  --window-size=1600,1000 --virtual-time-budget=20000 `
  --screenshot=ref.png "https://mizuki.mysqil.com/"

--virtual-time-budget 是给页面留出执行 JS 的时间，不然截到的是骨架。

2. 从构建产物里抠数值

截图只能看出「大概多宽」，具体多少 rem 得看 CSS。参考站的样式表地址就写在 HTML 里：

# 从首页 HTML 里列出所有 stylesheet
[regex]::Matches($html, '<link rel="stylesheet" href="([^"]+)"')

拉下 variables.css 一看，颜色变量和本站几乎一模一样——因为两边的 variables.styl 同源。真正的差异全在布局变量上：

变量	参考站	本站（改之前）
`--page-width`	`90rem`	`75rem`
单侧栏宽度	`17.5rem`	`17.5rem`（但只有一栏）
栅格列数	1 / 2 / 3 栏	1 / 2 栏

这一步很关键：如果颜色本来就一致，那"不像"就一定出在结构和尺寸上，不用去瞎调配色。

3. 写个探针页量真实宽度

CSS 里写了 17.5rem 不等于页面上真的是 280px——中间可能被 grid 轨道、max-w、flex 收缩改掉。所以做了一个临时页面，把各容器的 getBoundingClientRect() 读出来直接画在页面上，再截图：

const w = (sel) => {
  const el = document.querySelector(sel);
  const r = el.getBoundingClientRect();
  return `${Math.round(r.width)} @x${Math.round(r.left)}`;
};
probe.textContent = [
  `grid=${w("#main-grid")}`,
  `sidebar=${w("#sidebar")}`,
  `main=${w("main")}`,
  `rightSidebar=${w("#right-sidebar")}`,
].join("\n");

:::note[这一步救了我一次] 第一次量出来的结果是 sidebar=171 / main=845 / rightSidebar=360，而预期是 280 / 816 / 280。三栏宽度全错，但页面看上去"还行"，肉眼根本发现不了。原因见下面第三节的第一个坑。 :::

二、改了哪些地方

页面栅格：75rem → 90rem，三栏在 1280px 出现

- grid-cols-[17.5rem_auto]                    /* 一直都是两栏 */
+ grid-cols-1
+ md:grid-cols-[17.5rem_minmax(0,1fr)]
+ xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem]

列数变化和参考站一致：

视口宽度	布局
< 768px	单栏：正文 → 左栏 → 右栏 → 页脚
≥ 768px	两栏：左栏 \| 正文
≥ 1280px	三栏：左栏 \| 正文 \| 右栏

两个细节：

正文列写成 minmax(0, 1fr) 而不是 auto。 auto 轨道的下限是"内容的 min-content 宽度"，小屏上它经常比屏幕还宽，会把整个网格顶出去、右侧内容被裁掉。
跨列的元素要加 min-w-0。 右侧栏在窄屏是 col-span-2 横跨整行，不加 min-w-0 的话它会按内容最小宽度去撑轨道。

横幅底部那条波浪

这是参考站最有辨识度的东西，实现方式比想象的朴素——不是 mask 也不是 clip-path，就是一条 SVG 路径叠了 4 次：

<svg viewBox="0 20 150 32" preserveAspectRatio="none">
  <defs>
    <path id="gentle-wave"
          d="M-160 44c30 0 58-18 88-18s 58 18 88 18 58-18 88-18 58 18 88 18 v48h-352z" />
  </defs>
  <use href="#gentle-wave" y="0" class="opacity-25" style="animation-delay:-2s; animation-duration:7s" />
  <use href="#gentle-wave" y="3" class="opacity-50" style="animation-delay:-3s; animation-duration:10s" />
  <use href="#gentle-wave" y="5" class="opacity-75" style="animation-delay:-4s; animation-duration:13s" />
  <use href="#gentle-wave" y="7" class="opacity-100" style="animation-delay:-5s; animation-duration:20s" />
</svg>

.wave-layer {
  fill: var(--page-bg);            /* 关键：波浪的颜色就是页面底色 */
  animation: wave-move 25s cubic-bezier(.5,.5,.45,.5) infinite;
}
@keyframes wave-move {
  from { transform: translate(-90px, 0); }
  to   { transform: translate(85px, 0); }
}

三个要点：

fill 用 var(--page-bg)，看起来就像页面背景从下面漫上来把横幅"切"掉了。换主题色、切深浅模式时波浪会自动跟着变色，一行 JS 都不用写。
preserveAspectRatio="none" 必须有，否则波浪不会随宽度拉伸，窄屏上会缩成一团。
4 层的差异只有 y 偏移（0/3/5/7）、不透明度（25/50/75/100）和时长（7/10/13/20 秒）。时长互质、延迟取负值，波纹就不会同步，形成"水在错位流动"的视差感。

首页横幅文字：不给整幅图加遮罩

参考站的横幅正中有站点大标题，但它没有铺一层黑色遮罩（那样会把图压暗）。可读性全靠文字自己的阴影：

.banner-title    { text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.7); }
.banner-subtitle { text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.6); }

副标题在配置里，不想要就把两个字段都留空：

banner: {
  homeText: {
    title: "Xieluyang 的小屋",
    subtitle: "记录一些值得记下来的东西",
  },
}

导航栏：顶部透明，滚动后毛玻璃

改之前它是一张不透明卡片，!rounded-t-none 贴着屏幕顶端。改成和参考站一致的两态：

/* 默认：不透明卡片 */
#navbar > .navbar-bar {
  background-color: var(--card-bg);
  border-radius: var(--radius-large);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

/* ① 顶部：完全透明，让横幅透出来 */
#navbar[data-has-banner="true"]:not(.scrolled) > .navbar-bar {
  background-color: transparent;
  box-shadow: none;
  border-color: transparent;
}

/* ② 滚动后：毛玻璃 */
#navbar[data-has-banner="true"].scrolled > .navbar-bar {
  background-color: rgba(255, 255, 255, 0.55);
  backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.55);
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
}

.scrolled 由一段十几行的脚本控制：

const SCROLL_THRESHOLD = 50;
const syncScrolled = () => {
  const top = window.scrollY || document.documentElement.scrollTop || 0;
  navbarEl.classList.toggle("scrolled", top > SCROLL_THRESHOLD);
};
window.addEventListener("scroll", syncScrolled, { passive: true });
syncScrolled();   // 首屏可能是带着滚动位置刷新的，先同步一次

阈值取 50px：一点就变卡片会显得神经质，太大又迟钝。

首页顶部的分类筛选条

参考站首页第一屏是一条独立的卡片：🏠 | 归档 8 | 各分类。做成 CategoryBar.astro，几个细节：

pill 有三种状态，用属性而不是 class 控制：默认 / :hover / [data-active]（当前分类填充主题色）
分类多的时候可以横向滚动，滚轮直接转成横向滚动，不用按 shift
两侧有 2.5rem 的渐隐遮罩，滚到头/尾会消失，提示"还有更多"
脚本按 URL 里的 ?category= 高亮，并挂到 Swup 的 page:view 上——本站是无刷新跳转，换页后必须重新按当前地址算一次

文章卡片：把"底部两行小字"换成图标小块

参考站的卡片信息层级很清楚：标题 → 元信息（日期 / 分类 / 字数，每项都是"图标小块 + 文字"）→ 摘要 → 标签 chip 行。

改之前，字数和阅读时长是卡片底部一行灰色小字：

<div class="text-sm text-black/30">1736 words | 9 minutes</div>

现在并进 PostMeta，和日期、分类排成一行：

<div class="flex items-center">
  <div class="meta-icon">
    <Icon name="material-symbols:article-outline-rounded" class="text-xl" />
  </div>
  <span class="text-50 text-sm font-medium">1736 words</span>
</div>

标签单独排一行 chip（这一行 Fuwari 原本没有）：

<div class="flex flex-wrap gap-2 mt-2">
  <a href="..." class="btn-regular h-6 text-xs px-2 rounded-lg active:scale-95 group/tag">
    <span class="transition-transform group-hover/tag:translate-x-0.5"># Markdown</span>
  </a>
</div>

左侧栏：加公告卡，目录搬进来

参考站左栏的顺序是：个人资料 → 公告 → 标签 → 目录。

公告卡是新加的，可以关掉，关掉后记在 localStorage 里：

export const announcementConfig: AnnouncementConfig = {
  enable: true,
  title: "公告",
  content: "欢迎来到我的小站～ 这里主要记录一些学习笔记和折腾过程。",
  link: { text: "了解更多", url: "/about/", external: false },
};

目录从"右侧浮动栏"改成"左栏卡片"，这是迫不得已：整页 90rem + 左右各 17.5rem 侧栏之后，两边已经塞不下第四条浮动栏了（算一下：90 + 2×18 = 126rem ≈ 2016px 才够）。参考站本来就是侧栏目录，正好一致。

技术上有个坑：目录的 #toc 是 Swup 的替换容器之一，而侧栏不在替换容器里。最后是这样解决的——卡片外框常驻，#toc 放在里面，靠 CSS 的 :has() 决定显不显示：

/* 默认不显示，只有 #toc 里真的渲染出了 <table-of-contents>（也就是文章页）才显示 */
.toc-widget-card { display: none; }
.toc-widget-card:has(table-of-contents) { display: block; }

用 :has() 而不是在服务端判断，是因为侧栏不参与 Swup 替换——服务端算出来的显隐状态在跳页后不会更新。

卡片补一条极淡的描边

深色模式下卡片底色只比页面底色亮一档，光靠底色分层不够明显：

.enable-card-border .card-base {
  border: 1px solid var(--line-divider);      /* rgba(255,255,255,.08) */
  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
}

三、五个坑（都不报错，只是静默失效）

这一节是本文的重点。下面每一条都是"构建成功、页面能看、但效果是错的"。

1. Tailwind 扫不到拼出来的类名 ⚠️ 最隐蔽

我图省事，把侧栏宽度抽成常量再插值：

const sidebarCol = `${SIDEBAR_WIDTH}rem`;
const mainGridClass = [
  `md:grid-cols-[${sidebarCol}_minmax(0,1fr)]`,
  `xl:grid-cols-[${sidebarCol}_minmax(0,1fr)_${sidebarCol}]`,
].join(" ");

Tailwind 是靠"扫描源码文本"来生成 CSS 的。 源码里根本不存在 xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem] 这个字符串，只有一堆 ${}，所以这条规则压根不会生成。

后果不是报错，而是 grid-template-columns 完全没生效，三个块退化成"按内容自适应"，实测宽度变成 171 / 845 / 360。

修正很简单——写死字面量：

const mainGridClass = [
  "grid-cols-1",
  "md:grid-cols-[17.5rem_minmax(0,1fr)]",
  sidebarConfig.enable ? "xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem]" : "",
].join(" ");

:::warning[这类坑的共同点] 没有报错、没有警告、构建成功、页面"看起来还行"。 只有用探针量出 171/845/360 才暴露。所以别省那一次测量。 :::

2. Astro 不转义组件 prop 里的换行

给组件传多行字符串会直接编译失败：

<!-- ❌ 报 Unterminated string literal -->
<RightSideBar
    class="col-span-2 col-start-1 row-start-3 mb-4
           lg:row-start-2 lg:col-span-2"
/>

原因是 Astro 把"组件 prop 的字符串"原样塞进 JS 字符串字面量，且不转义里面的换行符。普通 HTML 元素上的多行 class 没这个问题（那是当 HTML 直接输出的）。

修法：算好再传，或者写成一行。

<!-- ✅ -->
<RightSideBar class={rightSideBarClass} />

3. Tailwind v3 和 v4 的断点不是一回事

参考站用 Tailwind v4，而且它的配置改写了断点：

前缀	Tailwind v3 默认	参考站（v4 + 自定义）
`md`	768px	768px
`lg`	1024px	1280px
`xl`	1280px	1920px

所以不能照抄 lg: 和 xl:。移植时的映射关系是：

参考站的 md: → 本站 md:
参考站的 lg: → 本站 xl:
参考站的 xl: → 本站 2xl:

一开始我差点去改 tailwind.config.cjs 的 screens 好让前缀一致，但那样会顺手改掉全站所有既有 lg: 的含义，风险太大，最后还是老老实实逐条换算。

4. 无头浏览器不推进 CSS transition（把我骗了一次）

验证毛玻璃效果时，我用探针读出这样的结果：

② 滚动 120px 后
  class            = "z-50 onload-animation group scrolled"   ← 类加上了
  background-color = rgba(0, 0, 0, 0)                          ← 却是透明的？
  backdrop-filter  = blur(0px)                                 ← 0 像素？

看起来像"类加上了但样式没生效"。实际原因是：无头浏览器里 CSS transition 不会推进，getComputedStyle 返回的是过渡的起始值。blur(0px) 正是从 none 过渡到 blur(20px) 的第 0 帧。

验证方法是把过渡关掉再读：

bar.style.transition = "none";
nav.classList.add("scrolled");
void bar.offsetHeight;        // 强制重排，让新样式立即生效
getComputedStyle(bar);        // 这时候读到的才是最终值

② 手动加 .scrolled（已禁用过渡）
  background-color = rgba(255, 255, 255, 0.55)      ✓
  backdrop-filter  = blur(20px)                     ✓
  border-color     = rgba(255, 255, 255, 0.55)      ✓
  box-shadow       = rgba(0,0,0,0.1) 0px 4px 16px   ✓

样式本来就是对的，是测量方法有问题。

5. 一个把 CSS 偷偷吞进依赖图的 glob

这个坑之前就埋着，这次重新构建时踩到了：ImageWrapper.astro 里为了动态加载图片写了

const files = import.meta.glob("../../**", { import: "default" });

../../** 等于 src/**，把 src 下所有文件都塞进了 Vite 的依赖图，包括 src/styles/*.css。副作用是全局样式"顺便"生效了——但加载顺序不可控，Tailwind 处理 @apply 时偶尔会报 The 'link' class does not exist，构建随机失败（大约 5 次里挂 1 次）。

修法两步：

把这个 glob 限定成图片后缀，它本来也只该管图片
全局样式改成在 Layout.astro 里显式 import，顺序写死（变量 → 公共类 → 各样式文件）

import "../styles/variables.styl";
import "../styles/main.css";
import "../styles/markdown.css";
// ...

顺带还把跨文件的 @apply 展开了（markdown.css 里 @apply link 依赖 main.css 先处理完），彻底消除顺序依赖。

四、怎么确认改对了

光看"我觉得像了"不算数。这次的验收手段有三个：

探针量数值 —— 关键容器宽高写进页面再截图，和参考站对比。最终 sidebar=280 / main=816 / rightSidebar=280，整页 1440px，和参考站完全一致。
无头截图对比 —— 1600×1000 视口下逐区块比对，深浅色各来一遍（--blink-settings=preferredColorScheme=1 可以强制浅色）。
astro check + biome check —— 保证没引入新的类型错误和格式问题。（astro check 还剩 2 个错误，都是改动之前就存在的：Navbar.astro 里 Svelte 组件的 client:only 类型、archive.astro 里的 PostForList 类型。）

五、结果

对着参考站逐项核对，现在一致的部分：

整页 90rem、单侧栏 17.5rem、断点 768 / 1280
横幅底部的四层视差波浪 + 首页居中大标题（靠文字阴影保证可读性）
导航栏顶部透明、滚动 50px 后变毛玻璃（白 55% + 20px 模糊）
首页分类筛选条（可横向滚动 + 当前分类高亮）
文章卡片：标题竖线、图标小块式元信息、摘要、# 标签 chip 行、右侧封面
左侧栏顺序：个人资料 → 公告 → 标签 → 目录
卡片统一的极淡描边与投影

功能上一点没丢：目录、站点统计、日历、音乐播放器、看板娘、Others 菜单都还在，只是换了位置和长相。

六、给以后的自己

改版式之前先量，改完再量一次。 可视化对比会骗人，数字不会。
Tailwind 的类名必须是字面量。 任何 ${} 插值都当成"这条规则不存在"来预期。
Astro 组件 prop 不要写多行字符串。
v3 和 v4 的断点前缀含义不同，跨版本抄代码一定先对表。
无头浏览器里读 transition 属性会读到起始值，验证样式要么禁用过渡，要么读规则的最终值。
import.meta.glob 的通配符要收窄。 ../../** 这种写法会把整个 src 拖进依赖图，副作用难以预料。

参考

参考站：https://mizuki.mysqil.com/
Mizuki 主题源码：https://github.com/LyraVoid/Mizuki
Fuwari 主题：https://github.com/saicaca/fuwari
Tailwind 断点文档：https://tailwindcss.com/docs/responsive-design

博客更新日志：接入 giscus 评论区

Sat, 26 Sep 2026 00:00:00 GMT

</div>

从今天起，每篇文章的底部都有了评论区。这一篇记录一下它是怎么接进来的、为什么这么选，以及中途踩到的两个坑。

评论存在哪里

评论区用的是 giscus，一个把 GitHub Discussions 变成评论框的开源组件。

它和常见的评论系统不太一样的地方在于没有独立的服务器和数据库：

你在评论区发的每一条，实际上都是仓库 xieluyang912/fuwari 里 Discussions 的一条回复
页面上只嵌入一个 iframe，评论数据全部存在 GitHub 上
因此不会出现「评论服务商跑路了，评论全没了」这种事 —— 数据跟着仓库走

代价是评论需要用 GitHub 账号登录。如果你没有 GitHub 账号，或者所在网络访问 GitHub 不稳定，那就没法评论了。这个取舍我选择了前者：数据掌握在自己手里，比多几个匿名评论更重要。

怎么评论

滚动到文章底部（评论区在版权声明下面）
点「使用 GitHub 登录」授权一次
写下想说的话，提交

评论同时会出现在仓库的 Discussions 里，地址是 https://github.com/xieluyang912/fuwari/discussions，在那边也一样能回复。

为什么选 giscus

本站是纯静态站点 —— Astro 构建出一堆 HTML，托管在 GitHub Pages 上，构建完成之后没有任何服务端代码。这意味着：

带服务端的评论系统（云函数 + 数据库那一类）要多维护一套东西，还可能产生费用
自建服务还要操心备案、续费、被刷
而 giscus 只需要前端嵌一个 iframe，成本是零

:::note[分类上的一个小设计] Discussions 里我建了一个 Announcements 类型的分类来存评论。这个类型只有管理员和 giscus 机器人能发起 discussion，访客只能回复、不能自己开新帖 —— 相当于从源头挡掉一部分垃圾内容。 :::

两个踩到的坑

1. 无刷新跳转会让脚本「失忆」

本站在用 Swup 做页面切换，点站内链接不会整页刷新，只替换 <main> 和目录这两个容器。

最开始我把 giscus 的加载脚本写在评论区组件里 —— 也就是 <main> 内部。结果有两个问题：

每次页面跳转，脚本都会被重新执行一次，可能重复插入评论区
更麻烦的是：访客如果从首页进来，压根没渲染过文章页的组件，脚本也就没机会注册；之后从首页跳到文章页，评论区不会加载

所以最后把加载逻辑挪到了 src/layouts/Layout.astro：它在每个页面上都存在、又不在 Swup 替换的范围内，整站只注册一次，再由 Swup 的 page:view 事件按需注入 iframe。

2. 明暗配色不能听系统偏好

giscus 官方推荐的配置是 data-theme="preferred_color_scheme"，意思是跟随操作系统的深浅色设置。

但本站的明暗模式是独立的：访客可以在显示设置里手动选浅色、深色或「跟随系统」，这个选择存在浏览器本地，和系统的实际设置未必一致。如果评论区单独跟着系统走，就会出现页面深色、评论区浅色的割裂感。

解决办法是监听 <html> 上 dark 类的变化 —— 访客在站内一切换主题，就用 postMessage 通知 iframe 换配色。用通知而不是整块重新加载，评论区不会闪一下。

最后

欢迎在下面试试。如果不想登录 GitHub、或者想直接聊，导航栏和侧边栏都能找到我。

黄霄雲2026.9.26「宇宙无敌号」苏州站歌单

Sat, 26 Sep 2026 00:00:00 GMT

</div>

现场曲目记录，按演出顺序整理，共 33 首。

开场 / Part 1

《重返地球》
《Oracle》
《淬炼》
《蝴蝶夫人》
《11》
《打开》

Part 2

《此生不换》
《劫》
《要不然我们就这样一万年》
《淬羽风华》
《怜心》

Part 3

《年少心动雨季》
《背对背拥抱》 cover 林俊杰
《没语季节》
《留不住的夏天》
《人鱼之歌》
《甲乙丙丁》 feat. 李佳薇
《失忆》嘉宾独唱

:::note[乐队秀] 马克老师弹奏了《弯弯的月亮》，纪念刘欢老师。 :::

Part 4

《平行线》
《小云》
《月牙湾》
《Sad Sometimes》
《带我去很远地方》
《烟火里的尘埃》

烟火打鼓秀

大屏合唱互动环节

《没语季节》+《带我去很远地方》+《你真的够了》+《回音如果》+《人鱼之歌》+《小云》

Part 5

《但愿人长久》 cover 邓丽君
《梦返》

点歌互动

《连名带姓》 cover 张惠妹
《可惜没如果》 cover 林俊杰
《羽众不同》
《盲选》

抽奖环节

Part 6 / 安可

《你的答案》
《回音如果》
《星辰大海》

项目介绍

Sat, 26 Sep 2026 00:00:00 GMT

项目介绍：Xieluyang 的个人博客

</div>

一个基于 Fuwari 主题二次开发的纯静态个人博客，用 Astro 构建，源码中所有关键位置都补充了中文注释。

一、这是什么

这是 Xieluyang的个人博客站点。站点本身不含后端服务，所有页面在构建时一次性生成 HTML，属于标准的静态站点（SSG），因此可以零成本托管在 GitHub Pages、Cloudflare、Vercel 等任意静态托管平台上。

项目	值
站点标题	Xieluyang
站点语言	简体中文（`zh_CN`）
主题色相	250（青色偏蓝），对访客开放调色
线上地址	`https://xieluyang912.github.io/fuwari/`
文章数量	4 篇（`src/content/posts/`）

二、技术栈

核心框架

Astro 5.13.10 —— 构建框架，负责把 Markdown、组件编译成静态 HTML
Svelte 5 —— 用于少数需要客户端交互的组件（搜索框、明暗切换、目录等）
Tailwind CSS 3.4 —— 原子化样式方案，开启嵌套语法
Stylus —— 少量全局样式与 CSS 变量定义

功能型依赖

依赖	作用
`@swup/astro`	站内跳转无刷新，带过渡动画
`astro-expressive-code`	代码块高亮增强（行号、折叠、语言角标、复制按钮）
`pagefind`	构建期生成全文搜索索引
`astro-icon` + Font Awesome 6	图标系统，通过 Iconify 名称引用
`katex` / `remark-math` / `rehype-katex`	数学公式渲染
`photoswipe`	文章内图片点击放大
`@astrojs/rss` / `@astrojs/sitemap`	RSS 订阅源与 sitemap.xml
`reading-time`	估算文章阅读时长

工程化

pnpm 9.14.4（preinstall 钩子强制只允许 pnpm）
Biome 2.2.5 —— 代码格式化与 lint，CI 中执行 biome ci
TypeScript 5.9 —— 配置对象有完整类型定义，编辑器可提示
GitHub Actions —— 三条工作流：代码质量检查、构建检查、自动部署

三、目录结构

fuwari/
├── astro.config.mjs        # 构建配置：集成、Markdown 管线、部署地址
├── wrangler.jsonc          # Cloudflare Workers 静态托管配置
├── biome.json              # 代码风格规则
├── pagefind.yml            # 搜索索引生成配置
├── scripts/new-post.js     # 新建文章的脚手架脚本
├── docs/                   # 官方多语言 README（11 种语言）
├── public/favicon/         # 不经构建直接复制的静态资源
├── .github/workflows/      # CI：biome.yml / build.yml / deploy.yml
└── src/
    ├── config.ts           # ★ 站点总配置文件，日常只改这一个
    ├── types/config.ts     # 上述配置的类型定义
    ├── content/
    │   ├── config.ts       # 文章 frontmatter 的字段校验规则
    │   ├── posts/          # 所有 Markdown 文章 + img/ 配图
    │   └── spec/about.md   # 「关于」页正文
    ├── layouts/            # Layout.astro（页面骨架）、MainGridLayout.astro（栅格布局）
    ├── pages/              # 路由：首页分页、归档、文章详情、about、rss.xml、robots.txt
    ├── components/
    │   ├── *.astro         # 导航栏、页脚、文章卡片、正文渲染等
    │   ├── control/        # 分页、返回顶部、按钮等小控件
    │   ├── widget/         # 侧边栏：个人资料、分类、标签、目录、显示设置
    │   └── misc/           # 图片包装、版权声明、Markdown 容器
    ├── plugins/            # 自定义 remark / rehype / Expressive Code 插件
    ├── i18n/               # 11 种语言的界面文案
    ├── styles/             # 全局样式、Markdown 样式、代码块与滚动条样式
    ├── utils/              # 内容、日期、URL、设置相关的工具函数
    └── assets/images/      # 横幅图、头像等需要被构建处理的图片

四、功能特性

明暗主题 + 自定义主题色 —— 访客可实时调节色相，配色通过 CSS 变量全局联动
文章目录（TOC） —— 基于 remark-sectionize 按标题层级切分，右侧浮动导航，随滚动高亮
站内全文搜索 —— 构建后由 Pagefind 扫描 dist/ 生成索引，纯前端检索，无需服务端
代码块增强 —— 行号、--collapse 折叠、语言角标、自定义复制按钮、diff 与高亮标记
Markdown 扩展语法
- 提示框：::note、::tip、::important、::caution、::warning
- 也兼容 GitHub 的 > [!NOTE] 写法
- GitHub 仓库卡片：::github{repo="owner/repo"}
- 数学公式：行内 $...$ 与独立 $$...$$
图片放大 —— 集成 PhotoSwipe，点开文章配图可全屏查看
阅读体验细节 —— 自动估算阅读时长、标题锚点链接、自定义滚动条、返回顶部按钮
响应式布局 —— 侧边栏在移动端折叠为抽屉式面板
RSS 与 SEO —— 输出 rss.xml、sitemap-index.xml、robots.txt，页面带 OG 标签

五、配置方式

日常维护只需要改 src/config.ts 一个文件，它导出五个配置对象：

导出常量	控制内容
`siteConfig`	标题、副标题、语言、主题色相、首页横幅、favicon
`navBarConfig`	顶部导航链接（内置首页 / 归档 / 关于，可加外链）
`profileConfig`	侧边栏头像、昵称、签名、社交链接
`licenseConfig`	文章底部版权声明（当前为 CC BY-NC-SA 4.0）
`expressiveCodeConfig`	代码高亮主题

所有配置在构建时被读取并写进静态页面，因此修改后需重新构建才会生效。各项字段的类型定义见 src/types/config.ts，编辑器会给出提示与报错。

部署相关的配置在 astro.config.mjs：site 与 base 必须与最终访问地址一致，否则 sitemap、RSS 里的绝对链接和静态资源路径都会出错。当前配置对应 GitHub Pages 的项目仓库地址 https://xieluyang912.github.io/fuwari/。

六、本地开发与构建

环境要求：Node.js ≥ 20、pnpm ≥ 9（首次使用需 npm install -g pnpm）。

pnpm install          # 安装依赖
pnpm dev              # 启动开发服务器，默认 http://localhost:4321
pnpm build            # 构建生产版本到 dist/，并自动生成搜索索引
pnpm preview          # 本地预览构建产物
pnpm check            # 检查类型与代码错误
pnpm new-post <文件名> # 新建一篇文章
pnpm format           # 用 Biome 格式化 src/
pnpm lint             # 用 Biome 检查并自动修复 src/

七、内容写作

新建文章推荐用 pnpm new-post <文件名>，生成的文件位于 src/content/posts/，顶部 frontmatter 格式如下：

---
title: 文章标题
published: 2026-09-25
description: 文章摘要，用于列表页展示和 SEO 描述
image: 'img/cover.png'    # 封面图，相对当前文章目录
tags: [标签一, 标签二]
category: 分类名
draft: false              # 为 true 时不会被构建进站点
lang: ''                  # 仅当文章语言与站点语言不同时才填
---

配图统一放在 src/content/posts/img/ 下，用相对路径引用。

八、部署

站内已配置两条部署路径，二选一即可：

1. GitHub Pages（当前主用）

.github/workflows/deploy.yml 会在推送到 main 分支时自动执行：安装依赖 → pnpm build → 上传 dist/ → 发布到 Pages。

前置条件：仓库 Settings → Pages → Source 需设为 "GitHub Actions"。 CI 中使用 --frozen-lockfile，保证依赖版本与本地一致。

2. Cloudflare Workers（静态资源模式）

站点是纯静态的，不需要 adapter 也不需要 Worker 脚本，Cloudflare 直接把 dist/ 当静态资源托管：

pnpm build && npx wrangler deploy

配置见 wrangler.jsonc，Worker 名为 xieluyang-blog。两个平台互不影响，可以同时存在。

辅助工作流

build.yml —— 在 Node 22 / 23 两个版本上跑 astro check 与 astro build，确保兼容性
biome.yml —— 代码风格检查

九、相对原主题的改动

相比上游 saicaca/fuwari，本仓库主要做了以下本地化调整：

全量中文注释 —— src/config.ts、astro.config.mjs、wrangler.jsonc、 .github/workflows/deploy.yml 等关键文件都写明了每个配置项的作用与注意事项，降低了后续维护（尤其是隔一段时间回来改）的成本。
站点信息替换 —— 标题、语言、主题色、导航链接、个人资料卡片、横幅图均改为本站内容。
部署地址适配 —— site / base 调整为 GitHub Pages 项目仓库形式，并新增 GitHub Pages 自动部署工作流。
内容填充 —— 新增自我介绍、大创项目资料、网站维护备忘录等文章与配套配图。

十、参考

Fuwari 主题：https://github.com/saicaca/fuwari
Astro 文档：https://docs.astro.build
Expressive Code 文档：https://expressive-code.com
Pagefind 文档：https://pagefind.app
本项目源码：https://github.com/xieluyang912/fuwari

许可

主题部分遵循 MIT License。文章内容采用 CC BY-NC-SA 4.0 协议。

你好，这是我的个人blog

Fri, 25 Sep 2026 00:00:00 GMT

</div>

欢迎来到我的博客。这是第一篇文章，简单介绍一下我自己，也介绍一下这个网站。

关于我

我是 Xieluyang，目前在四川大学就读临床医学。

关于这个网站

这个站点是用 Fuwari 搭建的，它是一个基于 Astro 的静态博客模板，作者是 saicaca。我选它的原因主要是：纯静态、加载快、开箱即用的功能比较全，而且样式清爽。

它自带的功能包括：

明暗主题切换，还支持自定义主题色
文章目录（TOC），长文阅读时自动生成右侧导航
代码高亮，基于 Expressive Code，支持行号、diff 标记和代码块标题
站内搜索，构建时用 Pagefind 生成索引
RSS 订阅，地址是 /fuwari/rss.xml
Markdown 扩展语法，比如提示框、GitHub 仓库卡片
多语言支持，站点语言在 src/config.ts 里配置

部署方面，因为是纯静态站点，可以直接托管在 Vercel、Netlify、Cloudflare Pages 或者 GitHub Pages 上。

这里会写什么

想写什么就写什么(狗头)

联系我

GitHub：@xieluyang912
QQ：234259867

欢迎交流，也欢迎指出文章里的错误。

一个备忘录

Fri, 25 Sep 2026 00:00:00 GMT

</div>

创建新文章

pnpm new-post <filename>

推送项目到GitHub

git status                      # 查看改了哪些文件
git add .                       # 添加所有修改
git commit -m "说明"            # 提交到本地仓库
git pull --rebase origin main   # 先拉取最远端代码
git push origin main            # 推送到GitHub

文章图片相关

封面图

封面图写在文章开头的 frontmatter 里（图片文件放在 src/content/posts/img/ 下）：

image: ./img/cover.jpg

正文插图

图片文件放在 src/content/posts/img/ 下，用相对路径引用：

![图注文字](./img/photo.jpg)

实际效果（下面这张就是上面那行语法插进来的）：

视频相关

方式一：嵌入 B 站视频

把 bvid 换成视频的 BV 号。外面套一层 16:9 的容器，播放器就会跟着屏幕宽度自适应：

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
<iframe src="https://player.bilibili.com/player.html?bvid=BV1GJ411x7h7&page=1&high_quality=1&danmaku=0&autoplay=0" loading="lazy" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>
</div>

实际效果（BV1GJ411x7h7，滚到这里才会加载，不会自动播）：

不想要自适应、固定高度就够了的话，用简写版：

<iframe width="100%" height="468" src="//player.bilibili.com/player.html?bvid=你的BV号&autoplay=0" loading="lazy" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

怎么保证不自动播放

三个手段叠加，基本杜绝：

<iframe src="https://player.bilibili.com/player.html?bvid=xxx&autoplay=0" loading="lazy" ...>

别写 autoplay=1 —— B 站播放器默认就是不自动播放的，会自己播通常是因为复制来的模板里带了 autoplay=1
&autoplay=0 —— 显式关掉。这个参数在部分播放器版本上不太靠谱，所以还要配下面一条
loading="lazy" —— 浏览器原生懒加载：iframe 没滚进视口附近就压根不加载，没加载自然不可能出声。这条是浏览器层面的，比 B 站自己的参数可靠，附带还加快了首屏速度

另外浏览器本身有自动播放策略：带声音的自动播放会被拦截，只有静音才允许。所以哪怕参数失效，正常情况下也吵不到人。

真遇到顽固的自动播放，终极方案是「封面图 + 点击再加载」：先放一张封面，用户点一下才把 iframe 插进 DOM。需要的话我可以写成一个组件，在 Markdown 里一行就能用。

方式二：播放 mp4（站内文件或外链）

<video> 标签是浏览器原生的播放器，controls 负责显示进度条，width: 100% 让它跟着正文宽度走：

<video src="/fuwari/files/demo.mp4" controls preload="none" style="width: 100%; border-radius: var(--radius-large);"></video>

实际效果（这里用的是外链示例文件，换成你自己放在 public/files/ 下的 mp4 就是同样的效果）：

文件相关

文件放哪里

src/content/posts/img/ 只会处理图片，其他类型（zip / pdf / docx / xlsx / mp4）放到 public/files/ 下，构建时会原样复制出去，不做压缩和改名。

注意链接必须带上站点的 base —— 本站是 GitHub Pages 的项目仓库，base 为 /fuwari，写成 /files/xxx.zip 会 404：

[点此下载测试文件](/fuwari/files/test.zip)

想让浏览器直接弹下载、而不是在线打开，用 HTML 标签加 download 属性（Astro 的 Markdown 允许内嵌 HTML）：

<a href="/fuwari/files/test.zip" download>📥 下载测试文件（523 B）</a>

实际效果

已建好一个测试文件，点下面这个链接就能下载到：

<a href="/fuwari/files/test.zip" download>📥 下载测试文件 test.zip（523 B）</a>

包内是一个 test.txt 和一份说明，用来确认下载链路是通的。

几点注意

public/ 里的文件会一起进 git 仓库，单文件别超过 100 MB（GitHub 限制），大文件建议放网盘或对象存储再外链
文件名用英文、不带空格，免得 URL 编码后出幺蛾子
在线预览 / 直接下载取决于浏览器对文件类型的处理，压缩包一定是下载，pdf 和 txt 多半是直接打开 —— 要强制下载就加 download