2026-10-07
维护记录
完成的工作
- 把 CI 从「一堆散落在 YAML 里的 shell」改成「薄 YAML +
bin/*.sh」 ✅- 触发原因:用户认为当前工作流不健康(诊断结论:仓库有两个作者 —— 用户和 CI 里的 bot,根因是本地不跑 CI 会跑的 fixer,典型事故是
0a651bd一次误改 230 个文件、b68a395改名 225 篇后要51aa901补 25 篇 aliases) - 用户口径(原话):「将 github action 重写,CI 中运行的脚本后续以本地 shell 脚本的方式编写,除非是 CI 环境或者是 github 强制依赖的操作,否则都在本地的 shell 中完成」,随后澄清「脚本还是在 github action 上运行,不是本地运行,只是接触了 yaml 编写工作流的依赖」
- 于是设计成:YAML 只声明触发条件 /
permissions/environment/ 第三方 action / 工具链安装 /concurrency,逻辑全部在bin/*.sh,本地跑同一个脚本就复现 CI 的结果
- 触发原因:用户认为当前工作流不健康(诊断结论:仓库有两个作者 —— 用户和 CI 里的 bot,根因是本地不跑 CI 会跑的 fixer,典型事故是
- 新增
bin/脚本层(11 个文件,bash 3.2 兼容 —— macOS 自带 bash 3.2 没有**、关联数组、mapfile)✅bin/lib.sh:被 source 的底座(定位仓库根、把 vendored 的.tools/deno/bin前置进 PATH、log/ok/warn/fail、run_step+CHECK_FAILED+report的「失败不中断、最后汇总」累加器、shell_syntax_check、sha256_of)bin/preflight.sh(--check只读 /--fix就地修 /--re-stage修完重新入 index,五步:① 文章文件名 ② Markdown 格式 ③ front matter ④ 单测 ⑤ 构建产物新鲜度)、bin/validate-posts.sh、bin/test.sh(含全部 shell 文件的bash -n语法检查)、bin/build.sh、bin/build-wasm.sh、bin/artifacts.sh、bin/check-links.sh、bin/publish-autofix.sh(CI 专用,本地跑会被拒绝)bin/hooks/pre-commit(preflight --fix --re-stage)与bin/hooks/pre-push(preflight --check)+bin/install-hooks.sh(写成core.hooksPath=bin/hooks,所以 hooks 是版本化文件,升级 / 回滚不用重装)
- 四个 workflow 全部瘦成壳 ✅
deploy.yml:checkout(去掉多余的submodules: true,本仓库没有.gitmodules)→ setup-deno(v2.x→ 钉死'2.9.5')→deno install -g -A npm:prettier@3.9.6→ actions-hugo →./bin/preflight.sh --fix→./bin/build.sh→ 上传 Pages →./bin/publish-autofix.shtest-scripts.yml/validate-posts.yml/check-dead-links.yml同样只剩一行调用(./bin/test.sh/./bin/validate-posts.sh/./bin/check-links.sh),paths 里补上bin/**
- 新增「构建产物新鲜度」检查(本仓库最容易忘的两件事)✅
bin/artifacts.sh:图片侧检查assets/src/bg/*.png → static/bg/*.avif(源图缺产物 = 硬失败并提示跑deno task optimize-images;只比 mtime 才 warn,避免新克隆时误报),wasm 侧读指纹清单比对- 新产物
themes/sdttttt-paper/assets/wasm/particles.sha256:sha256sum 格式(故意不用 JSON,bash 3.2 里解析 JSON 不值当)记「产物 1 行 + 源文件 4 行」。CI 不装 Rust,所以靠这份指纹就能发现「改了wasm/**却忘了重建」;本地有 cargo 时--rebuild会重编译 +cmp做最强校验 - 实测指纹
cac4cbe7… particles.wasm,与独立验证的 sha256 完全一致(32062 字节);--rebuild重编译 0.27s、逐字节一致 ⇒ 产物可复现
scripts/rename-posts.ts新增--check只读门禁 ✅- 语义:一个字节都不许改,但「有待改文件」本身就是失败(退出码 1),用来在本地 / CI 断言「当前内容 == CI 会产出的内容」;
deno.json新增rename-posts-checktask - skipped 明细在
--check下压成一行(否则每次刷 225 行「已是新格式」) scripts/__tests__/rename-posts-execute.test.ts新增 2 个 CLI 端到端测试(不合规范 → 退出码 1 且文件不动;已规范化 → 退出码 0)
- 语义:一个字节都不许改,但「有待改文件」本身就是失败(退出码 1),用来在本地 / CI 断言「当前内容 == CI 会产出的内容」;
- 文档同步:
AGENTS.md(新增bin/目录说明与「CI 与本地检查」一节、提交规范指向./bin/preflight.sh、wasm 重建要连指纹一起提交)、README.md(常用命令加./bin/preflight.sh/./bin/install-hooks.sh,补一句「workflow 只是壳,CI 跑的是bin/*.sh」)✅ - 验证:
./bin/preflight.sh(只读)与./bin/preflight.sh --fix都在 1.9s 内五步全绿,退出码 0;deno task test31 passed (142 steps);hugo --minify通过;./bin/publish-autofix.sh在本地如设计般拒绝执行(退出码 2)
遇到的问题
- bash 3.2 +
set -u下$VAR紧跟全角字符会被当成变量名的一部分 ⚠️ -ok "产物已更新:$WASM_ARTIFACT(…"直接报WASM_ARTIFACT(: unbound variable(bin/build-wasm.sh: line 23),因为(的多字节序列被当成了名字里的字符。全仓库 grep 出 9 处(preflight.sh:35/55/58、check-links.sh:24、artifacts.sh:65/90/94/135、build-wasm.sh:23),统一改成${VAR}(。附注:位置参数$1后面跟全角是安全的(bash 只取一位数字),字母变量名才有这个坑 --check第一版会真的改名 ⚠️ - 加了--check解析却忘了让它隐含 dry-run,于是/tmp/checkprobe里实测:打印「--check:需要重命名 1 篇文章」之后紧接着「✓ 重命名 1 篇文章成功」并 exit 0 —— 一个号称只读的门禁把文件改了。修法是dryRun = --dry-run || --dryRun || --check,并补了「文件名必须一个都不动」的端到端测试守住它- 本机没有全局
deno⚠️ -deno: command not found,但仓库里有 vendored 的.tools/deno/bin/deno(2.9.5)。bin/lib.sh因此负责把.tools/deno/bin前置进 PATH —— 顺带也解决了prettier:.tools/deno/bin/prettier是 deno 的 shim,自己要求 PATH 上有 deno bash -n只吃第一个文件 ⚠️ -bash -n bin/*.sh静默只检查了第一个,语法错误会漏。shell_syntax_check()改为逐个文件循环
下次建议
./bin/install-hooks.sh还没有执行:它会写用户的git config core.hooksPath,属于动本地配置,等确认后再装- 尚未实跑的路径:
bin/publish-autofix.sh(本地会拒绝,只能在 CI 里验)、bin/check-links.sh(要打外网)、bin/build.sh单独跑、preflight --re-stage;lib.sh的sha256_stream目前没人调用(疑似死代码,下次清理时确认) - 「工作流不健康」还剩四条没有落地也没有被否决的修法:① 文件名与正文 hash 解耦(现在改正文就会改 URL,只能靠
aliases兜)② front matter 只留一份真相(文件与 Hugo 缓存 / 索引之间的重复)③themes/sdttttt-paper/assets/js/*.js(1557 行)零测试 ④ 本地 git 身份是github-actions[bot],用户自己的提交也挂在 bot 名下 - 本次改动已随同一次提交推送:
ci: 把 workflow 逻辑搬进 bin/ 脚本层
第二轮跟进(同日,用 gh 看过 CI 之后)
- 先看线上跑得怎么样 ✅ -
440b746上四个 workflow 全 success(Hugo on GitHub Pages / Check Dead Links / Validate Posts / Test Scripts);build 日志里bin/preflight.sh五步全绿(ok preflight 通过(fix))、hugo 建 270 页、Commit auto-fix results: ok 没有需要提交的改动——bin/publish-autofix.sh正确 no-op,「两个作者」的问题第一次没有发作。唯一的告警是 Node 20 弃用(跑在 Node 24 上)和ubuntu-latest的迁移预告 - 升 action 大版本(就是那条 Node 20 告警)✅ - 四个 workflow 里的
actions/checkout@v4→v7,加上 deploy 专用的actions/configure-pages@v5→v6、actions/upload-pages-artifact@v3→v5、actions/deploy-pages@v4→v5。逐个核过 breaking change:checkout v6 只是把persist-credentials改存$RUNNER_TEMP,v7 新增的allow-unsafe-pr-checkout只影响pull_request_target/workflow_run的 fork checkout;v4 的 upload-pages-artifact 不再打包 dotfiles —— 实测find public -name '.*'0 个,对我们无影响。setup-deno 与 peaceiris/actions-hugo 已是最新 - 死链检查拆出「被服务器拦住」 ✅ -
scripts/check-dead-links.ts新增BLOCKED_STATUSES = new Set([401, 403, 429, 451])、isBlockedStatus()、partitionByStatus(),先报死链(stderr、退出码 1)再报「N 个链接被服务器拦住、没能验证(不算死链)」;bin/check-links.sh在「没有死链、但有被拦住」时也写一条 job summary。本地实跑:20 条告警 → 3 条真死链 + 17 条被拦住(13 条百度百科?fromModule=lemma_inlink反爬、StackOverflow、2 条github.com/user-attachments、1 条 451) - 反爬域名不参与判定 ✅ - 同一批百度百科链接在同一份代码上时而 403、时而 404(并发 6 个请求打到同一家站时偶发 404),于是「真死链」数量每次跑都不一样。新增
ANTI_CRAWL_HOSTS = {baike.baidu.com}+isAntiCrawlHost():这些域名下拿到的任何状态都归「没能验证」 - 收掉最后一条真死链(归档允许清单) ✅ -
scripts/check-dead-links.ts新增ARCHIVED_URLS+isArchived():已知失效、且正文里已注明「仅作存档」的链接连请求都不发,单列一栏「已归档」,不计入死链、不改退出码。清单自身也有测试守着 —— 每条都必须在正文里真的出现、且带一句说明,否则就成了「悄悄放行一条死链」 - 日志噪声与死代码 ✅ -
rename-posts默认只打一行「跳过 N 篇(…加 –verbose 看明细)」(以前刷 229 行);删掉bin/lib.sh里从未被调用的sha256_stream - 修两个站内 404(都是写在 changelog 正文里的历史 URL)✅ -
content/changelog/_index.md新建,用aliases: ["/maintenance/"]给旧地址留活路;content/posts/20260817-文章的变化-277.md补全 5 条历史 alias(05hog4→03wwo2→-jtc→-1e69→-dqo→-277,用 YAML 块式写) - 顺手修掉
addAlias的一个 latent bug ✅ -scripts/rename-posts.ts里识别「aliases:+ 缩进数组」的正则认不出 Prettier 把方括号也折成多行的写法([与]各占一行),会落到块式分支、插出aliases:+- "…"+[ … ]这种非法 YAML —— 仓库里已经有 2 个文件是这个形态(content/posts/20230912-关于查找自己想要的软件的问题-pyx.md、content/posts/20250504-C中的指针运算-类型转换以及函数指针-dsq.md),下一次改名就会让 Hugo 构建失败。修法:正则的(.*)换成([\s\S]*?)、[ \t]+\[放宽成[ \t]*\[;scripts/lib/frontmatter.ts同步支持折行数组(并在parseScalar丢掉尾逗号产生的空项);两处各补测试 - 验证:
./bin/preflight.sh五步全绿(33 passed / 150 steps,其中--fix --re-stage这条路 —— 正是 pre-commit hook 的命令 —— 也跑通了);hugo --minify→ 270 页 / 250 aliases;public/maintenance/index.html已生成且跳/changelog/;./bin/check-links.sh→ 2 条死链(就是本次刚修的两个站内 404,部署后即消失)+ 17 条没能验证 + 1 条已归档 - 部署后复验 ✅ -
de9b9ea推上去后四个 workflow 全 success(Hugo on GitHub Pages 1m7s、Check Dead Links / Validate Posts / Test Scripts 均 ~13s);actions/checkout@v7生效后 日志里再也找不到 Node 20 弃用字样;两个站内 URL 现在都返回 200(https://sdttttt.online/maintenance/、https://sdttttt.online/posts/20260817-文章的变化-1e69/);手动gh workflow run check-dead-links.yml重跑一次 → 0 条死链 + 17 条没能验证 + 1 条已归档,不再挂::warning::
遇到的问题(第二轮)
partitionByStatus第一版把 200 的链接也算进死链 ⚠️ - 只按isBlockedStatus(status)分组、忘了原来那句!statuses.get(url)!.ok,于是「能打开」的链接也进了 dead 组。新加的 3 个单测当场抓住(ok 的链接两组都不进失败,actual 里混进了那个ok.example的链接),补一句if (entry.ok) continue;后全绿- 给 section 加
_index.md会把标题清空 ⚠️ - 写完content/changelog/_index.md(只为了aliases)之后构建出的标题变成<title>- 海边。把文件移开重建才确认:原本的 “Changelogs” 是 Hugo 按目录名生成的,一旦有了_index.md就改从文件取。所以必须在文件里显式写title: "Changelogs"—— 这种「加了文件反而丢东西」的改动,只能靠改动前后各构建一次对比来发现 - Prettier 会把长 alias 数组折成多行 ⚠️ - 5 条 alias 写成 inline 时 Prettier 会折成
[/ 各项 /]各占一行,而那正是上面那个 latent bug 的触发形态。改用 YAML 块式(aliases:+- "…")后 Prettier 保留原样,addAlias与parseFrontMatter也都认 - 同一批链接每次跑出来的死链数量不一样 ⚠️ - 第一次跑 3 死链 + 17 没能验证,第二次变成 2 + 16:变的是那条
baike.baidu.com/item/UDP/571511(并发 6 个请求打到同一家反爬站时它偶尔回 404;curl 与 deno 单独打都稳定 403)。这类看人下菜的回的码不能当成链接坏了 —— 所以有了ANTI_CRAWL_HOSTS - 在 changelog 里写例子 URL 会被自己的死链检查抓 ⚠️ - 记录「新测试抓住了混进来的
ok.example链接」之后,check-links当场把那个.example域名报成死链(DNS 失败)。行内代码块拦不住(正则只是停在反引号前),要么反引号也不写 scheme,要么放进围栏代码块
下次建议(第二轮)
- 两条站内 404 已在部署后复验为 200(Hugo 的 alias 页是 200 + meta refresh,死链脚本看的就是 200)
- 剩下的都是「工作流不健康」那条线上的老账(见第一轮的下次建议):① 文件名与正文 hash 解耦(现在改正文就改 URL,只能靠
aliases兜)② front matter 只留一份真相 ③themes/sdttttt-paper/assets/js/*.js(1557 行)零测试 ④ 本地 git 身份是github-actions[bot]。本次已与用户确认:四条都先不做,留档待议 check-dead-links.yml的 push 触发保留(paths收窄为content/**、scripts/check-dead-links.ts、bin/check-links.sh、自身):内容改了顺手查一次外链,这次的两条站内 404 就是它抓出来的。只有每周 cron + 手动触发则为备选./bin/install-hooks.sh按用户要求不装(不动本地git config core.hooksPath);hooks 文件本身已在仓库里,需要时手动跑一次即可
第三轮(同日):把 themes/ 合并成单一主题
- 触发:用户先纠正「我的主题是
themes/sdttttt-paper/不是themes/hugo-paper/」,随后定调「@themes/ 只保留一个吧,我不打算和上游同步了」—— 即放弃「父主题 vendor-in + 子主题 override」的双层结构 ✅ - 三个决定(ask_user_question 收敛):① 保留
sdttttt-paper目录名(把 hugo-paper 独有文件git mv进来,7 个同名冲突留子主题现有版本);② 只搬站点真正需要的(layouts/assets/static/i18n/+theme.toml+LICENSE,丢掉images/(2.5MB 截图)exampleSite/bun.lockpackage.jsonpostcss.config.mjsscripts/go.mod与父主题 README);③ 顺手清理全部选上(highlight.min.js+theme.png+ 8 个社交图标 svg +custom.css里失效的@reference './app.css';) - 执行:
git mv31 个文件进themes/sdttttt-paper/(assets/{app,main}.css、layouts/404.html、layouts/_default/single.html、layouts/partials/{head,math,mermaid}.html、layouts/shortcodes/collapse.html、static/theme.svg、LICENSE+ 21 个i18n/*.yaml),再git rm -r themes/hugo-paper(54 个文件)→themes/从 106 文件 / 3.06MB 变成 52 文件 / 384KB - 验证(这一步是整件事的关键):改动顺序刻意排成「先纯合并、验证零差异,再动注释和配置」——
- 基线
hugo --minify -d /tmp/theme-refactor/before:608 个文件 - 合并后
after-A:598 个文件,diff -r只有 10 行Only in before(就是那 10 个被授权的静态资源),没有任何一行differ - 全部改完(模板注释 / 配置 / README / custom.css)后再构建
after-B,先剥 HTML 注释、再把main.min.<64位hash>.css与integrity归一化,diff 仍然只剩「10 个被删静态资源」+「CSS 文件名 hash 变了」两项。CSS 逐 token 比对过,差异只有@reference './app.css';这一处
- 基线
- 配置与引用一次性收口:
hugo.toml的theme = ["sdttttt-paper", "hugo-paper"]→theme = "sdttttt-paper";.prettierignore删themes/hugo-paper;deno.json的 lint exclude 换成themes/sdttttt-paper;AGENTS.md(开头段、子主题 bullet、themes/hugo-paper/目录条目、hugo.toml描述、整节「主题同步分两部分」)、根README.md、scripts/lib/frontmatter.ts、themes/sdttttt-paper/README.md(整篇重写成独立主题说明)、theme.toml尾注、9 个模板文件头注释(统一改成 “upstream sync was dropped on 2026-10-07 … this file is now the only copy — edit it freely”) - 收益:部署体积 10,272KB → 10,180KB;删掉的 10 个静态资源合计 67,234 字节(
highlight.min.js48,833 /theme.png7,991 / 8 个社交 svg 10,410);main.min.css61,457 → 61,434 字节(少的就是那行 Tailwind 指令) - 构建:270 页 / 62 paginator / 11 static(原 21)/ 250 aliases,264ms,无 warning;
./bin/preflight.sh五步全绿
遇到的问题(第三轮)
- 「sitemap 里 210 个
/posts/loc」是自己数错的 ⚠️ - 一开始把grep '/posts/' public/sitemap.xml | wc -l得到的 210 当成文章数,据此去改AGENTS.md里那句「= 209 篇」。后来发现那 210 里有 1 条是/posts/分区页本身;去掉它正好 209,与public/searchindex.json(同一套where site.RegularPages "Type" "in" site.Params.mainSections过滤)的 209 条完全对上 → 原有的 209 是对的,改动已回滚。教训:同一个过滤条件在 sitemap / searchindex / 归档页三处都有产出,跨口径核对比盯着一个数字置信 - theme list 是「叠加」不是「二选一」,引用父主题的路径不等于改了父主题 ⚠️ - 上一轮我引用
themes/hugo-paper/layouts/partials/head.html:99说明 og:image 的管道,被读成「碰了不是你的主题」。实际上theme = ["sdttttt-paper", "hugo-paper"]让两个主题同时参与渲染,子主题没覆盖的文件本来就由父主题提供 —— 要改必须 fork 进子主题,我从没建议编辑父主题。教训:提到某个文件时要讲清它「由谁提供、渲染时归谁」,否则路径本身就会被当成所有权声明 @reference './app.css';是 Tailwind 的编译期指令,却混进了发布 CSS ⚠️ - Hugo 不跑 PostCSS(head.html里没有| postCSS),所以这行字面量一直躺在main.min.css里。删掉后 CSS 的 sha256 变了 → 所有 HTML 的<link>与integrity属性跟着变,做产物 diff 时必须把这两个都归一化,否则会看到 329 个「差异」- minify 后的 HTML 是一整行,
diff等于什么都看不见 ⚠️ - 第一次做规范化 diff 时 329 个文件全报「不同」,逐字节都看不出差在哪。解决办法是perl -0pi -e 's/</\n</g'先把标签拆成行再 diff —— 与上一轮「加_index.md会把标题清空」是同一类问题:只能靠改动前后各构建一次做对比 main.css里还留着一处url(./theme.png)⚠️ - 来自非monoDarkIcon分支的 arbitrary utility.[background:url(./theme.png)_left_center/_auto_theme('spacing.6')_no-repeat];本站monoDarkIcon = true,HTML 用的是theme.svg变体,这条规则永远匹配不到,所以删掉theme.png不会 404(已 grep 全部产物确认没有任何 HTML 引用它)
下次建议(第三轮)
themes/sdttttt-paper/assets/app.css现在也成了「无人引用」的文件(它唯一的引用者就是刚删掉的@reference行)。它是main.css的 Tailwind 源码,留着能看出编译前的原貌;想更干净可以删- 上游 hugo-paper 的改动以后只能临时 clone 对比、手动挑(
git clone --depth 1 … /tmp/hp-clone),不再有「sync 一次就够」的路径 - 本次改动尚未提交(
git status:31 rename + 54 delete + 16 modify),等确认后再推
第四轮(同日):主题改名 sdttttt-paper → self
- 触发:用户说「主题的名字 不要叫做 sdttttt-paper 了,换成 “self”」✅
- 执行:
git mv themes/sdttttt-paper themes/self,然后把 19 个文件里的sdttttt-paper一律换成self:- 目录与配置:
hugo.toml(theme = "self"+ 上面那段注释)、theme.toml(name/licenselink/description)、deno.json的 lint exclude - 构建脚本:
bin/lib.sh的WASM_ARTIFACT/WASM_MANIFEST两行(bin/artifacts.sh与bin/build-wasm.sh都靠它们,改路径只改这一处)、bin/build-wasm.sh注释 - 指纹文件:
themes/self/assets/wasm/particles.sha256第一行的路径 —— 产物哈希没变,所以不需要重编译 wasm - 文档:
AGENTS.md(开头段 + 6 处路径)、根README.md、themes/self/README.md、.gitignore注释 - 主题内注释:
assets/custom.css、assets/js/search.js、layouts/index.json、layouts/_default/{baseof,list,search}.html、layouts/partials/{header,footer,bg}.html
- 目录与配置:
- 验证:改名前后各构建一次(598 文件 → 598 文件),
diff -r完全为空,产物逐字节一致。主题名不出现在任何发布产物里,理论上本就不该有差异;这一步是为了证明「没有哪个模板或资源是靠主题名拼路径的」。改名后全仓库(排除content/changelog/的历史记录)已无sdttttt-paper残留 themes/self/README.md的 History 节补了一行改名记录,并保留2026-10-05那行里的旧名(那是当时的历史事实)theme.toml的description从「sdttttt’s personal fork of hugo-paper」改成「The Hugo theme behind sdttttt.online (forked from hugo-paper)」./bin/preflight.sh五步全绿、./bin/artifacts.sh check通过
遇到的问题(第四轮)
themes/self/README.md的表格又被 prettier 拦下 ⚠️ - 表头那一列从`themes/sdttttt-paper/`缩成`themes/self/`,整列宽度跟着变,prettier 会重排对齐 → 跑一遍format-markdown即好。教训:这张表的列宽是 prettier 自动对齐的,改任何一个单元格都要跟着格式化一次sdttttt-paper有两类出现,不能无脑替换 ⚠️ - 一类是「当前的名字」(配置、注释、脚本变量),另一类是「历史记录」(content/changelog/*里记录当时的状态、themes/self/README.md的 History 节)。前者必须换,后者必须留 —— 所以替换时显式用-g '!content/changelog/**'排除整目录,README 的历史那行再手工改回
下次建议(第四轮)
themes/self/assets/app.css依然是「无人引用」状态(见第三轮建议),要不要删仍未定- 主题现在叫
self(hugo.toml里theme = "self"),以后写文档提到它时统一用这个名字
第五轮(同日):砍掉不需要的功能(RSS / description / 死代码)
需求原文:「theme中有些我不需要的功能,就删除吧, 例如description, 还有RSS生成,我都不需要」。
完成的工作(第五轮)
- RSS 全站关闭 ✅ — 关键点是只从
home去掉"RSS"关不干净:Hugo 对section/taxonomy/term有自带的 RSS 默认值,/tags/*/index.xml、/changelog/index.xml都是从那儿来的。所以hugo.toml的[outputs]现在写成home = ["HTML", "JSON"]+ 把section/taxonomy/term逐个钉成["HTML"]。效果:页面数 270 → 258(少掉的 12 个正好是 12 个 feed,线上那 ≈3.26MB 的订阅文件全部消失),find确认产物里除sitemap.xml外没有任何.xml <meta name="description">删除 ✅ — 只删主题侧那两行(文章页取.Summary、其余页取site.Params.description)。225 篇 front matter 的description一个都没动:它喂的是_internal/opengraph.html/twitter_cards.html/schema.html,实测产物里og:description/twitter:description/itemprop=description三处仍是那句手写描述,而head.html那行输出的才是 8162 字符的.Summary。删掉 head 那两行后.Summary只剩搜索索引在用。head.html 与hugo.toml里都留了注释说明这件事,免得以后有人把description当成死字段一起删了- 评论 / 数学 / mermaid 删除 ✅ —
single.html的 Disqus / GraphComment / giscus / mermaid 四块(hugo.toml里对应参数一个都没配过)、head.html的 math partial 调用,以及partials/math.html、partials/mermaid.html两个文件。localKatex分支引用的katex.min.css/auto-render.min.js本来就不在static/里,等于这条路从来跑不通 - highlight.js / shortcode / 死配置删除 ✅ —
head.html的 highlight.js loader(disableHLJS = true一直关着它)、layouts/shortcodes/collapse.html(全站 0 次短代码调用,shortcodes/目录随之删空)、hugo.toml的enableInlineShortcodes与ignoreErrors - 社交图标导航整块删除 ✅ — 这一块从来就没能用过:
baseof.html的social_params列了 twitter / github / … 八个名字,header.html按名字去拼./twitter.svg,但themes/self/static/里只有theme.svg,那些 SVG 一个都没 vendor 进来;而hugo.toml也没设过任何社交参数,所以它只会渲染成空盒子。它的rss分支还指向已经不存在的/index.xml。删掉social_listscratch + preload 循环 + nav - 瘦身 ✅ —
i18n/从 21 个 yaml 砍到只剩zh.yaml(站点是 zh-only,实际只查prev_page/next_page两个键);.prettierignore删掉指向早就不存在的themes/PaperMod那行;scripts/validate-posts.ts删掉private字段检查(0 篇在用,连测试一起删,单测 34 → 33 个) - 文档同步 ✅ —
themes/self/README.md(把head.html/single.html补进「我们自己维护」的表、修掉那一行已经过期的「head.html is left untouched」、新增 2026-10-07 删除清单与「RSS 怎么恢复」两段)与AGENTS.md(主题描述里的文件清单、hugo.toml条目、front matterdescription的说明) - 验证 ✅ —
hugo --minify258 页 / 62 paginator / 250 aliases,211ms;./bin/preflight.sh五步全绿;deno task lint干净;抽查产物<head>已无 meta description、无 RSS<link rel="alternate">,og:description/twitter:description/itemprop=description仍在
遇到的问题(第五轮)
- 构建当场被自己的 changelog 文案搞挂了 ⚠️ - 日志里写了「全站 0 次」+ 短代码开始标记(双花括号加尖括号)这样一句,Hugo 会把它当 shortcode 开头解析,直接
ERROR error building site: ... unrecognized character in shortcode action: U+0060 '\’。**而./bin/preflight.sh五步全绿** —— 印证了第三轮就列出的那条:preflight 不跑hugo`,内容/模板层面的错要等到 CI 部署那一步才爆。在正文里提到 Hugo 短代码语法时别原样写那两个字符,或改用代码块 + 转义形式 site.Params.description并不是死配置,差点误删 ⚠️ - 原本以为删了head.html那行后它就没用了,于是问卷里把「删hugo.toml的description参数」也打包进去了。实际一构建才发现:Hugo 内建的_internal/opengraph.html/twitter_cards.html会回退到site.Params.description,首页 / 标签页 / 归档页这类没有 front matterdescription的页面全靠它拿og:description。删掉后对比旧产物:这三个页面从有描述变成完全没描述。已把参数加回来(它现在只喂分享卡片,不再生成<meta name="description">),并在hugo.toml注释里写明原因。教训:「主题里没引用」≠「没人引用」 —— Hugo 的_internal/*模板也是消费者,删配置前要看产物 diff- 改 README 表格必然触发 prettier 重排 ⚠️ - 第四轮已经踩过一次,这次又踩:新插的两行单元格宽度和别的行不一样,prettier 会把整张表按最长单元格重排 → 跑一遍
deno task format-markdown即好 grep在产物里搜到name=description/mermaid不代表没删干净 ⚠️ - 命中的两处都在content/changelog/的历史正文里(那些日志本身在讨论这件事),确认时要带上下文看,别只看grep -l- 删 RSS 的连锁面比想象中广 ⚠️ - 除了
[outputs]与head.html的AlternativeOutputFormats循环,还有header.html里rss社交项的index.xml硬编码。bin/*.sh、.github/workflows/*.yml、scripts/*.ts里确实没有任何index.xml引用,所以脚本层不用动
下次建议(第五轮)
bin/preflight.sh该加一步「hugo --minify -d <tmpdir>」—— 这一轮它拦不住的东西(短代码标记写法、模板语法错)只有构建能发现,而它现在跑到第五步全绿、下一步就是 CI 部署themes/self/assets/app.css还是「无人引用」的 Tailwind 源文件(连带main.css这份 61KB 构建产物也脱管),第五轮依然没结论 —— 删还是接回构建,需要明确决定- 剩下的优化项(探索时列过、这轮没做):
pt-wasm.js:59会把 rejected 的 compile promise 永久缓存住;徽标的待机 float 每帧都在整块putImageData
第六轮(同日):徽标透明度 —— 只留一个旋钮,方向先做反了一次
完成的工作(第六轮)
- 徽标透明度收成一个变量 ✅ —— 原先三处各写一遍:
html.at-bottom .page-bg__box的opacity: 0.85、prefers-reduced-motion块里的0.7、无 JS 兜底的0.85。现在:root { --page-bg-opacity: 1 },html.at-bottom/html:not(.js)/prefers-reduced-motion四处统一opacity: var(--page-bg-opacity)—— 亮色暗色共用一份值(用户明确要求「亮色也降低,不需要维护两份」)✅ - 删掉暗色专属的压亮滤镜 ✅ —— 修好死选择器之后它反而让暗色更淡,与诉求相反,直接删掉;暗色现在与亮色共用
.page-bg__box的基础处理 ✅ - 顺手修掉一条从来没生效过的暗色规则 ✅ ——
[data-theme="dark"] .pt-stage { … }是死代码:本主题的暗色是partials/header.html:62往<html>挂dark类(htmlClass[isDark ? 'add' : 'remove']('dark')),全仓库没有任何地方写过data-theme属性。改成html.dark .pt-stage后粒子演示页的暗色处理才第一次生效 ✅
遇到的问题(第六轮)
- 「降低透明度」被我按 CSS
opacity的字面方向做反了 ⚠️ - 用户说的是「暗色下显示不太好,透明度降低一些」= 要更实(更不透明),我却把opacity从 0.85 降到 0.6,还给暗色叠了一层brightness(0.9) saturate(0.85) blur(0.3px),结果用户一眼看出「更淡了」。教训:中文「透明度」是双向词(「提高」= 更透 / 「降低」= 更实),遇到它先确认「要更实还是更淡」再动手 —— 方向错一次就是整轮往返 ✅ - 「按模式各写一份」是伪需求 ⚠️ - 第一版写了「暗色专属」的 opacity 规则,还顺手踩了优先级:
html.dark .page-bg__box与html.at-bottom .page-bg__box都是 (0,2,1),只能靠「写在后面」取胜,得显式写成html.dark.at-bottom …才稳。改用共享的 CSS 变量后这类跨档覆盖全都不需要了 ✅ [data-theme="dark"]这种「看着合理」的选择器不会报错、只会静默失效 ⚠️ - 它既不在 linter 视野里,也不会在构建时报警;只能靠「谁在写这个属性」反查(rg data-theme全仓库只有 CSS 自己两处命中)才能发现。写暗色规则前先确认本主题用的是类还是属性 ✅
验证结果(第六轮)
hugo --minify0 报错;产物 CSS(head.html:34是main.css+custom.css→ concat → minify → fingerprint)实测含:root{…--page-bg-opacity:1}、opacity:var(--page-bg-opacity)×4,html.dark.at-bottom与html.dark .page-bg__box{filter:…}两条均已消失,html.dark .pt-stage{…}生效 ✅./bin/preflight.sh五步全绿(33 个单测)、bunx prettier@3.9.6 --check content/changelog/*.md通过 ✅
第七轮(同日):顶栏加 Search 菜单
完成的工作(第七轮)
- 顶栏加站内搜索入口 ✅ —— 只改
hugo.toml:新增一条[[menu.main]](identifier = "search"、name = "Search"、url = "/search/"、weight = 3),原Source的 weight 从 3 顺延到 4,导航顺序变成 Posts → Archive → Search → Source → About。模板不用动:themes/self/layouts/partials/header.html直接range site.Menus.main(移动端弹的是同一份列表的全屏抽屉),所以加菜单项 = 加一条菜单配置 ✅ - 标签统一用英文
Search,与既有的Posts/Archive/Source/About一致(页面内标题仍是content/search.md的中文「搜索」)✅ - 实测首页 /
/archives///search// 文章页四类页面的<nav>都渲染出五条入口且顺序一致;/search/页本身的autofocus输入框、/searchindex.json(267,503 字节)均正常 ✅
遇到的问题(第七轮)
- 「少了 12 页」虚惊一场 ⚠️ - 顺手对比构建摘要时发现 Pages 从 270 掉到 258(而 Aliases 反而 245 → 250),一度怀疑有文章丢了。实际上是这几轮之间的
c935ab8 refactor(theme): 删除 RSS 生成与一批死功能:[outputs]不再给 home / section / taxonomy / term 出 RSS,270 − 258 = 12 正好就是那些 RSS 输出。文章数没变(content/posts226 篇)✅ —— 教训:hugo摘要里的 Pages 包含 RSS / 分页等输出,跨提交比数字前先看清中间有没有动过[outputs]
验证结果(第七轮)
./bin/build.sh0 报错,Pages 258 / Aliases 250;./bin/preflight.sh五步全绿(33 个单测 / 150 steps)✅- 顺手确认了
themes/self/layouts/robots.txt(Allow: /)与public/sitemap.xml:/search/本来就在站点地图里,这次上导航不需要同步放宽任何抓取规则 ✅
第八轮(同日):把一篇私人文章从所有列表里摘出去
完成的工作(第八轮)
- 「今天是二零二六年十月二日」(写爷爷那篇)转为「私密文章」 ✅ —— 按仓库既有惯例(
意义/关于恋爱观/我所寄托的情感/自述-小学时期)在 front matter 加:没选1build: 2 list: never 3 render: truedraft: true:draft会让整篇不构建、直接链接也 404;list: never + render: true只把它从所有列表里摘掉(首页、分页、归档、标签、搜索索引、sitemap),知道链接的人仍能打开。改前专门问过用户,用户明确选后者 ✅ - 实测(
rm -rf public后重建):页面本身仍在(public/posts/20260921-今天是二零二六年十月二日-141g/index.html,8,668 字节);首页 /page/2/page/3//archives///tags//searchindex.json/sitemap.xml全部 0 命中;归档页计数 209 → 208 篇(线上 209、改后本地 208,对照确认)✅ - 对照组「今天是二零二六年九月二十一日」(同一天发的另一篇,不含私事)仍在首页与搜索索引里,未被误伤 ✅
- front matter 改了但文件名没变(hash 只取自正文):
preflight ① 文章文件名直接通过,没有触发改名、也没动 URL ✅
遇到的问题(第八轮)
- 「草稿」有两种含义,仓库里两种用法都真实存在 ⚠️ -
draft: true(AI编程/Paxos算法/程序的内部分段等)与build.list: never(那几篇私人文章)都有人用,但效果差很远(前者链接 404、后者链接仍活)。先问清再动手,省掉一次「发布后才发现链接挂了 / 还挂着」的往返 ✅
验证结果(第八轮)
./bin/build.sh0 报错,Pages 258 / Aliases 250;./bin/preflight.sh五步全绿(33 个单测 / 149 steps);deno task format-markdown-check通过 ✅
下次建议(第八轮)
- 以后再有「不想公开但想留档」的文章,照第八轮的做法加
build.list: never+render: true即可,别用draft(会连链接一起弄丢)✅
第九轮(同日):清掉 themes/self/assets/ 里指向已删页面的死 CSS
完成的工作(第九轮)
- 扫描口径:写了一个一次性脚本(
/tmp/scan_css.py,已删)—— 括号/引号感知地解析themes/self/assets/main.css,抽出每个选择器的主类 token,再与语料(public/**/*.html|xml|json|txt+themes/self/layouts/**+content/**+assets/js/**+static/**+hugo.toml)比对,列出「CSS 里有、源码/产物里从不出现」的类 ✅ - 删了 27 个选择器 +
@keyframes spin+--animate-spin变量声明(main.css选择器 337 → 310,只减不增;:root唯一变化就是少了--animate-spin):- 11 个来自已删除的社交图标导航(
header.html那块在 c935ab8 被删):.lg\:mt-0、.ltr\:lg\:ml-14、.rtl\:lg\:mr-14、.h-7、.w-7、.lg\:h-6、.lg\:w-6、.\[\&_svg\]\:m-auto ... svg、.\[\&_svg\]\:block ... svg、.\[background\:var\(--url\)_center_center\/cover_no-repeat\]、.hover\:animate-spin; - 13 个来自上游 exampleSite / 已删内容:
.invisible、.visible、.mx-6、.mt-24\!、.truncate、.border-\[0\.5px\]、.border-black\/10、.bg-black\/5\!、.bg-white\/50、.p-3、.outline、.dark\:bg-black\/80\!、.dark\:bg-white\/90\!(含 5 个连带清空的@supports (color:color-mix(...))块)
- 11 个来自已删除的社交图标导航(
monoDarkIcon这条遗留开关整条清掉(用户问过、选「彻底清」)✅:header.html硬编码theme.svg那套 class;head.html的$dark_icon条件改成固定的theme.svgpreload;hugo.toml删掉[params] monoDarkIcon = true与两行注释;themes/self/README.md里那行说明改成「2026-10-07 起monoDarkIcon与theme.png已删除,这是唯一图标」。顺带删掉它的两条配套死规则.\[background\:url(\.\/theme\.png)...\]与.\[transition\:_background-position_0\.4s_steps\(5\)\]——theme.png(7,991 B)在合并进themes/self/时已被删,开关又固定true,else 分支永不渲染(已 grep 全部产物确认)custom.css与 5 个 JS 都是零死代码,未动 ✅:page-bg.js/pt-wasm.js/search.js分别由bg.html/search.html引用,particles-wasm.js+particles.js由particles.html引用(后者是运行时动态注入的 Canvas 2D 降级引擎,页面只是draft: true而非被删);JS 里所有querySelector目标(.page-bg__box/__canvas/__png、pt-bg-config、pt-config、pt-canvas、search-*)在 layouts 里都存在;giscus/comment/katex/mermaid/hljs/social/rss/disqus/twitter/mastodon等关键词全库 0 命中- 收益:
main.css源文件 62,025 → 58,004 字节(-6.5%);hugo --minify产物 61,447 → 57,922 字节(-3,525 B / -5.7%)
遇到的问题(第九轮)
- 第一版删除脚本漏了开括号 ⚠️ -
res += sel + body + '}'写成了没有'{',输出 436 个}却只有 1 个{。教训:批量改 CSS 后必须校验括号数与「选择器集合只减不增」,光看字节数看不出来 ✅ .visible差点漏掉 ⚠️ - 扫描语料里若混入assets/js,particles*.js里的局部变量visible会让「字符串包含」判据误判成「有用」。改成按 class token 集合比对后浮出水面,再用['\"]visible['\"]+classList.*反查确认没有任何 JS 动态加这个类,才敢删 ✅- README.md 表格改措辞后 prettier 报错 ⚠️ - markdown 表格要按最长单元格重新对齐,直接
--write会让整张表 23 行全被重排。改成把新单元格裁到原宽度(381 字符)再补空格 → 只动 1 行。preflight ②当时就是这么红的 ✅
验证结果(第九轮)
./bin/preflight.sh五步全绿(33 passed / 149 steps)✅;hugo --minifyexit 0(258 pages,无报错)- 产物核对:新的
main.min.*.css里theme.png/steps(5)/visibility:visible全部 0 命中,theme.svg规则仍在;public/index.html渲出的深色按钮 class 与清理前逐字一致([background:url(./theme.svg)_left_center/cover_no-repeat] dark:invert dark:[background-position:right]),preload 仍是theme.svg;全部非 changelog 页面里theme.png引用数 = 0(只有 10-05 / 10-07 两篇维护日志的正文文字提到它) - 0 个「改了样式却没同步」的漏网:扫描脚本重跑后
UNUSED: 0
下次建议(第九轮)
- 再删主题里的整块功能时,顺手跑一遍这套 token 扫描(抽选择器主类 token → 与
public/**/*.html+layouts+content+assets/js求差集),比逐个 grep 靠谱 assets/侧已确认无死代码。若要继续瘦身,下一个候选是 21 个无var()引用的--tw-*孤儿变量(--tw-ring-shadow/--tw-shadow-color/--tw-drop-shadow-*/--tw-outline-style/--tw-translate-z/--tw-duration…):它们是 Tailwind 的@property+*,::before,::after,::backdrop初始化层按组发射的,.prose kbd:has(kbd)(来自app.css的@apply shadow-none)与.filter仍引用了一部分,收益只有几百字节、风险中等,本次未动
第十轮(同日):把 Tailwind 管线 vendor 回仓库,main.css 从「手删产物」换成「重编译产物」
完成的工作(第十轮)
- 重编译跑通且可复现 ✅:上游的三个构建配置从我们自己的 git 历史里找回(
git show e6f0a2e:themes/hugo-paper/{package.json,bun.lock,postcss.config.mjs},cf620fe 合并主题时删掉的)。本机 bun 1.3.14,bun install --frozen-lockfile装出与当初完全一致的版本(tailwindcss 4.1.18 / @tailwindcss/postcss 4.1.18 / @tailwindcss/typography 0.5.19 / postcss 8.5.6 / postcss-cli 11.0.1 / postcss-preset-env 11.1.2 / autoprefixer 10.4.23,179 包),postcss assets/app.css -o assets/main.css(cwd = 主题根)产出 57,943 B / 1690 行 / 313 选择器,连跑两次逐字节一致(sha256664872659995620d1e0aec658d5c015932c6c38d34c5fe41011eb69f5a2aefff) - 采纳重编译产物 ✅:
themes/self/assets/main.css从第九轮手删版(bd91385f…)换成重编译产物 —— 比 HEAD 少 30 条规则,其中 27 条正是第九轮手删的,另外.container/.contents/.shrink/.table/:where(.space-x-10 > :not(:last-child))是上游 exampleSite 留下的自繁殖化石,也一并消失 - 顺手补上两条真实缺失的规则 ✅:
.mb-10(themes/self/layouts/_default/particles.html:39)与.text-sm(同文件 :42)在模板里真的在用,却从来没有被编译进产物(HEAD 与第九轮手删版都缺);重编译后自动出现(该页draft: true,只影响本地hugo server -D) - 零回归验证 ✅:从
public/**/*.html的class="…"与assets/js的classList.*抽出 202 个真实 class token,逐个查规则 —— 新产物里「缺规则」的 60 个全部由assets/custom.css提供(arch*/btn-dark/img-lost*/is-active/js/at-bottom/language-*…)或本来就不是 Tailwind 类;「重编译缺、HEAD 却有规则」= 空集 - 管线 vendor 回仓库 ✅:
themes/self/{package.json,bun.lock,postcss.config.mjs}(bun.lock与postcss.config.mjs逐字照搬上游;package.json只改name/private/description并把scripts收成一条build:css,devDependencies 原样保留,因为 lockfile 里记着这一组、删掉就要重写 lockfile)+deno task build-css(=bin/build-css.sh:bun install --frozen-lockfile→postcss→artifacts.sh stamp-css)+ 产物指纹themes/self/assets/main.css.sha256(30 条 = 产物 + 主题内被扫描的 29 个文件) bin/artifacts.sh加了第 ③ 项check_css✅:与 wasm 同款(CI 不装 bun,靠指纹发现「改了源码没重编译」);check --rebuild在有 bun +node_modules时会把 CSS 重编译到临时目录逐字节比对;build-wasm.sh改调新名stamp-wasm(旧名stamp保留);CSS 路径集中在bin/lib.sh- 实测扫描范围就是主题目录 ✅:往仓库根丢一个带
flex-row-reverse的探针文件,产物里 0 命中;同一个类写进themes/self/layouts/**则立刻命中 —— 所以指纹取「整个themes/self/」是正好够用的范围 - 文档同步 ✅:
AGENTS.md(主题清单加 Tailwind 管线那一行 + 扫描范围警告、命令表、bin/清单、preflight ⑤ 口径、编码规范、推送前检查)、themes/self/README.md新增「The Tailwind pipeline」段与 History 一行
遇到的问题(第十轮)
- 不钉死 lockfile 就编不出同一份产物 ⚠️ - 第一次图省事只装了 6 个直接依赖(166 包),产物 57,903 B,与钉住 lockfile 的 57,943 B 差 40 字节,diff 出来是
initial-value: 0 0 #0000vsrgba(0,0,0,0)。原因:postcss-preset-env的传递依赖@csstools/*被重新解析到了更新的 patch 版本。结论:bun.lock必须原样 vendor + 永远--frozen-lockfile,连用不上的 prettier devDeps 也一起留着 ✅ - 「重编译」并不能自动洗掉历史沉积 ⚠️ - Tailwind v4 的扫描根就是编译时的 cwd(主题根),上一版
main.css自己也在扫描范围内,所以旧产物里的类会被重新发射(exampleSite/删了那么久,它的类还活着就是这个机制);实测主题根之外(仓库根_tw_probe.html)的文件不影响产物,主题内新增文件则立刻影响 —— 指纹范围因此取「整个themes/self/减去node_modules/assets/wasm/ 产物自身 / 指纹自身」✅ - 边扫边写会不会抖动 ⚠️ -
postcss -o assets/main.css的输出正是下一次的扫描输入,先验证过:就地连跑两次字节一致,且「就地编译」与「编译到 /tmp」结果相同,所以指纹里放产物自身是安全的 ✅ - README 里写什么词会被编译进去 ⚠️ - 这轮自己踩了一次:
themes/self/README.md新写的说明里带上了字面量dark-bg(app.css里@utility dark-bg的名字),重编译后main.css从 57,943 → 58,801 字节,diff 只有一行 ——.dark-bg:where(.dark,.dark *)多背了一层:not(#\#)特异性 bumpers(1 → 4)。把那句话改成「the dark-mode utility」后逐字节复原(sha256 回到664872659995620d1e0aec658d5c015932c6c38d34c5fe41011eb69f5a2aefff)。同时验证过收敛性:在 README 里留着这个词连跑 3 次,输出稳定不变(不会每跑一次再涨一层)✅
验证结果(第十轮)
deno task build-css在仓库里跑通,产物 sha256 与重编译前完全一致(幂等可反复跑)✅./bin/artifacts.sh check --rebuild全绿:cargo 重编译 wasm 逐字节一致 + bun 重编译 CSS 逐字节一致 ✅- 负例都拦得住:往主题里塞一个新文件、或手改产物 →
check立刻报「Tailwind 产物与源码不一致」并提示跑deno task build-css;恢复后转绿 ✅ ./bin/preflight.sh五步全绿;hugo --minifyexit 0 ✅- CI 侧无改动(
deploy.yml不装 bun):陈旧产物由 preflight ⑤ 的指纹检查拦住
下次建议(第十轮)
- 以后改样式只改
themes/self/assets/app.css(站点自有样式仍写assets/custom.css),别再手改main.css;推送前deno task build-css,产物与main.css.sha256一起提交 - 真要升级 Tailwind(换
bun.lock)时必须当成一次「样式回归」来验:重编译后与旧产物对选择器集合 + 用真实 class token 查一遍规则 themes/self/node_modules/已被.gitignore覆盖(含node_modules/通配),不必额外加规则