站点优化：资源瘦身、主题闪烁、可访问性与工程护栏（21 项） - #4
Merged
Merged
Conversation
导航栏 logo 原为 2400×741 / 860KB，实际只渲染 104×32，且 ThemedImage 把明暗两版都写进 DOM，浏览器两张都会下载——每个页面首屏为此付出约 1.5MB。地图页 6 张 1280×800 PNG 合计 8.36MB。 - logo 转 480px webp：860KB → 15KB，684KB → 16KB - 地图转 webp（q82）：8.36MB → 595KB - 新增 1200×630 分享图；原 og:image 是 3.24:1 的 logo，在分享卡片里 会被裁掉两头 - navbar logo 尺寸按真实比例改为 104×32（原 120×36 比例不符，占位偏差） - README 站点 logo 同步换 webp 构建产物 22M → 4.8M。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Docusaurus 在缺少 frontmatter description 时会抓正文第一句当描述， 结果搜索结果与分享卡片里显示的是「教程」「粒子效果」「玩家状态」 「趋光」这类无意义片段。 - 9 篇文档各补一句描述，同时写进 .md 与 .tiptap.json（json 是编辑器 的权威源，只改 md 会在下次保存时被导出覆盖） - 打开搜索框快捷键提示：表格型 wiki 里搜索是主入口，且表格单元格 内容确实已进入索引 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
8 篇文档的 frontmatter 全部写着 sidebar_position: 1，把文件名前缀 「1. 」~「8. 」提供的排序整个覆盖掉了。当前顺序只是并列时的回退结果， 再加一篇文档就可能乱序。 - 删掉这 8 篇的 sidebar_position，让文件名前缀重新决定顺序 （docs/intro.md 保留，它还带着 slug: /） - 进度碑刻成就名「s百年孤独」→「百年孤独」 两项都同步改了 .md 与 .tiptap.json。构建后侧边栏顺序已核对无误。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DataTable / Callout / ColorTable / Label 四个组件都用 useColorMode() 在 JS 里挑颜色。服务端渲染只能按 defaultMode（dark）烤死一种，构建产物里 `bg:'#BBBFC5'` 变成了 background-color:rgb(49,54,63)——浅色模式读者 首屏拿到深灰单元格，要等 521KB 的 main.js 水合完才翻回来。 改用仓库里 .ms-ink 已经在用的双变量模式：明暗两套值一起发出，由 CSS 按 [data-theme] 挑，服务端渲染不再与主题绑定。 DataTable 稍有不同：手动单元格色必须压过 `tbody td:first-child` 的首列 底色和 `tr:hover td` 的悬停底色，所以 backgroundColor 仍写成行内样式， 只是值指向变量。变量没有特异性之争，主题切换归 CSS、优先级归行内。 顺带： - 四处 useColorMode 全部移除，切换主题不再触发整表重渲染 - 删除 labelStyle()——注释说给旧编辑器用，但已无任何调用方 构建产物中不再有任何主题烤死的颜色值。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
横滚提示：宽表格靠横向滚动查看，但滚动条以外没有任何线索说明右边还有 列，读者容易以为数据到此为止。新增 useScrollAffordance，复用已有的 ResizeObserver + scroll 监听思路，能滚且未到头时给右缘加一道 mask 渐隐。 DataTable 与普通 Markdown 表格（MDXComponents 的 ScrollableTable）共用。 吸顶表头：.ms-table-head-sticky 原为 top:0，而导航栏是 sticky + z-index 200，往上滚导航栏滑回来时会整个盖住表头。改为让开 --ifm-navbar-height； navbar 开着 hideOnScroll，收起时再贴回 0，免得表头上方留一条空带。 移动端：原 996px 断点整段只处理 navbar/sidebar，正文和表格一条规则都没有。 新增 768px 断点收紧单元格内边距与字号，同样宽度下多露出一列。 行高：--ifm-line-height-base 2 → 1.75。中文正文常规区间，一屏多放约 15% 内容，对表格密集的页面收益最大。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
「能力一览」一页装 10 技能 + 14 天赋 + 7 灵魂宝物，读者想查某个能力的 冷却时间，路径是进页面 → 滚 → 找。页顶铺一排锚点直接解决。 索引从 Docusaurus 已有的 toc 数据现算，不写进文档内容——docs 下的 .md 是 .tiptap.json 的导出产物，手写进去会在下次用编辑器保存时被覆盖。新增 文档也自动带上。 选层策略取「条目数最多的那一层级」，且不足 6 条不渲染（右侧 TOC 已够用）。 各页结构差别很大，固定取某层会漏，取最深层也不对——全局机制的 h4 只有 4 条，远不如它的 10 条 h3 有用。实际效果： 能力一览 32 项（每个能力一个 h4） 全局机制 10 项 回响记录 10 项 地图导览 / 模式介绍 各 7 项 进度碑刻 / 饰品集册 / 文本套组详览 / intro 均不足 6 条，不渲染 @docusaurus/plugin-content-docs 提为 devDependency：swizzle 组件要从它的 /client 入口取 useDoc，包本身早已在依赖树里，只是类型解析不到。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
custom.css 首行的 @import fonts.googleapis.com 有两个问题：对国内读者 （本站主要受众）那个域名基本不可达，而且 @import 写在 CSS 首行是阻塞 渲染的。实际效果是国外读者看到 Noto、国内读者等 DNS 超时后回退系统字体， 两地视觉不一致且首屏被拖慢。 - 正文回落系统字体栈（PingFang SC / 微软雅黑 / 冬青黑），0 字节 - 标题衬线体是设计主特征，保留 Noto Serif SC，按全站用字裁成子集自托管： 1176 个汉字 + 拉丁基本区，400 与 700 两个字重合计约 470KB （600 全站没有任何规则用到，不生成） - 字体放 src/css/fonts/ 走打包器，自动带上 baseUrl 与内容哈希 - scripts/build-font-subset.mjs + `pnpm fonts` 负责重新生成，用 uv 跑 fonttools 不污染系统 Python；源字体缓存在 .cache-fonts/（已 gitignore） - scripts/font-charset.txt 留给 CI 比对，仓库用字超出子集时报错提醒 顺带补上 package.json 的 test 脚本：三个测试文件本来就在，但没有入口， 而且它们是普通 assert 脚本不是 node:test 套件，`node --test <目录>` 会失败。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
仓库此前没有 .github/。docusaurus.config.ts 设了 onBrokenLinks: "throw"， 但那只在有人真的跑构建时才生效——带坏链的改动会一路合进 main，直到 Cloudflare Pages 部署失败或有人本地构建才被发现。 .github/workflows/ci.yml：资源护栏 → typecheck → 编辑器往返测试 → build。 部署仍由 Cloudflare Pages 自己盯 main，CI 只验证。 scripts/check-assets.mjs 两道闸： - static/img 单文件 >500KB 直接失败。刚把 logo 从 860KB 压到 15KB、地图 从 8.3MB 压到 595KB，没有这道闸下次拖张原图进来就白做了 - 仓库用字必须落在 scripts/font-charset.txt 内，超出的字在标题里会逐字 回落系统宋体，提示跑 `pnpm fonts` 重生成 字符集扫描抽到 scripts/charset.mjs，与 build-font-subset.mjs 共用。 两道闸都验证过能正确 fail。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
对比度：按 WCAG 实算，浅色模式下 --ms-text-dim 只有 3.86:1、 --ms-text-muted 只有 2.19:1，都低于正文所需的 4.5:1。dim 用在引用块正文 和右侧目录，muted 用在注释文字，两处都是正文级别。调到 5.51:1 / 4.52:1。 深色模式下两者原本是同一个值，dim/muted 的层级差别整个丢了，拉开成 5.61:1 / 4.64:1。图标 token 复算过是 3.32:1 与 4.64:1，已过 3:1，不动。 渐变标题：.markdown h1 与首页 .titleZh 用 -webkit-text-fill-color: transparent + background-clip: text。不支持的浏览器上标题是全透明的—— 不是退回普通颜色，是彻底看不见。先给实色打底，渐变移进 @supports。 动效偏好：index.module.css 有 8 处 animation（含 3 个 blur(90px) 光球跑 18s 无限循环），prefers-reduced-motion 一处都没有；custom.css 里其实早就 为滚动和锚点闪烁做了这层保护。补一条整页兜底而不是逐个点名类——漏一个 就等于没做，以后新增的也自动落进来。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
前提：customCss 整段排在 Infima 之后（实测 Infima .navbar__link 在合并 样式表的 46239，本站样式起点在 220734）。同特异性时本站规则本来就赢， 只有 Infima 更特异或它自己带 !important 才真正需要 !important。 保守起见只动一簇：.navbar-github-link。该元素实际带 `navbar__item navbar__link navbar-github-link`，逐属性核对 Infima—— height / justify-content / font-size / letter-spacing / border-radius / background 它根本没有规则，display 与 padding 来自 .navbar__item、 color 来自 .navbar__link，都是同特异性。105 → 92。 transition 那条保留：移动端侧边栏里同一个链接会命中特异性更高的 .navbar-sidebar__items .navbar__link，其 transition 只含 background 与 padding-left，去掉之后 hover 变色会从渐变变成瞬变。移动端侧边栏那两条 整块保留，同理。 验证方式：对顶栏按钮与侧边栏链接两个元素模拟层叠（特异性 + !important + 源码顺序），比对改动前后的胜出声明。桌面完全一致；侧边栏唯一差异是 align-items 换了来源规则但值同为 center，计算样式不变。 其余簇（colorModeToggle / toggleButton / 搜索框 / 移动端）未动：它们在跟 Docusaurus 主题的 CSS Modules 抢优先级，且没有浏览器可肉眼复核。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Deploying midsoul-wiki with
|
| Latest commit: |
fb096d7
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3e0a0a04.midsoul-wiki.pages.dev |
| Branch Preview URL: | https://optimize-site-audit.midsoul-wiki.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
一轮全站审查后修复 21 项问题。按主题分成 10 个 commit，每条可独立 revert。
结果
static/img各 commit
294c5aaThemedImage把明暗两版都写进 DOM、浏览器两张都下载89c6b0a7bc99d1sidebar_position全是 1，把文件名前缀排序整个覆盖掉了；顺带修「s百年孤独」错别字76d0223useColorMode()在 JS 里挑颜色，SSR 按 defaultMode 烤死一种，另一主题首屏闪烁。改用仓库已有的.ms-ink双变量模式04c4aaatop:0会被 z-index 200 的 navbar 盖住）；新增 768px 移动端断点；行高 2 → 1.75898d54ec7f5081pnpm test入口6105d0af5680adprefers-reduced-motionfb096d7!important（105 → 92）。外观若有异常，revert 这一条即可说明
docs/**/*.md是.tiptap.json的导出产物，只改 md 会在下次用编辑器保存时被覆盖，因此 frontmatter / 图片路径 / 错别字都两边同改，并跑了往返测试。fb096d7不是靠猜：先实测确认 customCss 整段排在 Infima 之后，再逐属性核对，最后用层叠模拟器对比改动前后的胜出声明——桌面完全一致，侧边栏唯一差异是align-items换了来源规则但值同为center。pnpm fonts可复现（重跑 byte 级一致）。新增文档若用到子集外的字，CI 会报错提醒。待确认（未改动）
5. 回响记录.md的 Callout 写「共有 9 种回响」，但页面里有 10 个条目。像是加了第 10 个但计数没更新——属游戏数据，留给维护者定。需要人工过目
CI 四步本地全绿，但以下需肉眼确认：明暗切换无闪烁 / 吸顶表头不被导航栏盖住 / 手机端表格渐隐提示 / 标题渐变正常 / 顶栏「心火计划」按钮外观无变化。
🤖 Generated with Claude Code