# 2026-10-13 主题审查

> 图片转义与交互缺陷的复现、修复，以及主题和消费站点的本地验证记录。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> [!NOTE] 本地审查快照
> 本记录描述本地源码与测试。公开版本和抽样消费站点的模块版本仍为 `v1.2.0`。本次审查尚未发布或部署这些修复。

## 范围 {#scope}

审查开始时主题位于 `f8f476e`，共享工作树中已有消费站点维护、紧凑侧栏修改，以及进行中的英文文档修订。这些工作均被保留。审查期间，原有侧栏修复被单独提交为 `8f1f08d`，对应文件内容未发生变化。以下发现是额外的本地修复，不代表每行代码都经过了正式审计。

本次覆盖主题自有检查器、运行时单元测试、合成输出夹具、真实双语文档站，以及两类消费站点：DDIA 图书和 SILO 大型文档树。源码检查重点包括 URL 处理、图片输出、消息边界、焦点切换、运行时隔离与导航。视觉检查使用真实消费页面和文档站。

## 已复现缺陷与修复 {#repairs}

| 缺陷 | 触发方式与表现 | 修复与回归 |
| --- | --- | --- |
| 图片 URL 逃出 HTML 属性 | 普通图片或 Gallery 的 URL 中，引号后跟属性形状的查询值，会生成额外 HTML 属性；与号也可能改变浏览器解码后的 URL。 | URL 校验后再做 HTML 属性转义。`check-media-primitives.py` 解析 HTML、Print、RSS 中块级和行内图片属性；`check-gallery.py` 检查含引号的 Gallery URL。无执行代码的额外属性探针在修复前失败。 |
| Draw.io 丢失端点参数且消息处理不严谨 | 已有查询参数或片段的端点被拼接成错误的嵌入地址。空值或异常消息可能抛错，处理消息时也没有要求配置的源。 | 使用 `URL` 和 `searchParams` 构造地址；核对当前 iframe 与配置的源；忽略异常数据；向确切源发送消息，仅接受 PNG/SVG 图片导出 URL。新增 Draw.io 单元测试与站点编辑器集成测试覆盖这些路径。 |
| 页面操作菜单的键盘行为不完整 | ArrowDown 打开菜单时，CSS 可见性过渡尚未允许焦点进入；Tab 离开菜单后菜单仍保持展开。 | 可见性立即切换，保留透明度和位移动画；焦点离开整个控件后关闭菜单，且不抢回焦点。运行时和真实浏览器测试覆盖正向、反向遍历。 |
| 外观面板重开后被旧事件清除状态 | 在原生 `close` 事件排队期间立即重开面板，面板仍可见，`aria-expanded` 却变成 false。 | 面板已经重新打开时忽略此前的关闭事件。真实浏览器测试在 Chromium、Firefox、WebKit 的桌面与手机宽度覆盖该竞态。 |

两份分类页 HTML 快照也需要跟进已有侧栏修复：完整核对差异后，每份移除了 33 处错误的叶节点隐藏标记。随后 52 个输出面的快照检查通过，没有接受其他快照差异。

未发布行为已经写入双语 [架构](/zh/docs/design/architecture/) 与 [外壳](/zh/docs/design/shell/) 契约。此次修改无需配置迁移，也没有新增依赖。

## 验证 {#validation}

本地使用 Hugo Extended **0.166.0**、Go **1.27.1**、Node **26.9.0**、Pandoc **3.11**，PDF 生成使用 Chromium **151.0.7922.34**。这不等同于跑过固定版本的 CI，也不代表重新认证 Hugo 0.160.1 兼容下限。

| 层级 | 证据 |
| --- | --- |
| 主题运行时 | 修复后 52 项 JavaScript 测试全部通过。Python discovery 通过 116 项；90 项迁移测试还单独跑了一遍，不重复加到总数里。 |
| 主题检查器 | 执行全部 `bin/check-*.py`，包括带明确参数的输出安全检查，以及打包后的 EPUB/PDF 检查；配置 schema 生成检查通过。媒体、Gallery、输出与快照相关检查在修改后重新执行。检查器构建有效发布输出时使用警告即失败的门禁。 |
| 文档集成 | 本地主题替换下的 `make check` 通过：源码与渲染 Markdown、双语标题覆盖、内部链接、替代站点构建、favicon、输出快照和版本锁定契约。 |
| 浏览器集成 | `make browser` 的 **229 项测试** 通过，包含完整 sitemap 无障碍扫描、六种响应式宽度、中英文、导航、搜索、组件、代码、社区回归和四种外观预设。额外引擎检查的 **6 项测试** 通过，覆盖 Chromium、Firefox、WebKit 的 390 和 1440 px 视口。 |
| 出版夹具 | EPUB 包含 5 章、31 个链接目标，内部检查零错误；EPUBCheck **5.3.0** 零错误、零警告。PDF 共 23 页，5 个预期标题齐全，内部检查零错误，并抽查了渲染页。制品留在 Git 之外。 |
| DDIA 抽样 | 本地主题 `make check-local` 通过，包括 14 章翻译、196 处图片布局及第二版 57 页中的 38,170 个内部引用。抽查桌面、手机、暗色阅读页与四种样式菜单。 |
| SILO 抽样 | 本地主题 `make check` 通过，包括 1,552 个 HTML 文件中的 536,561 个内部引用。抽查桌面文档和手机搜索结果。 |

首次广泛测试发现了过期快照。一次独立安全检查调用也漏传了必需参数，修正后通过 493 份夹具输出检查。新增 Print 断言最初没有同步测试页面自身的输出列表，补齐测试设置后，HTML/Print/RSS 回归通过。这些问题均明确解决，没有当作首次成功。

## 性能观察 {#performance}

检查了文档站严格构建、压缩后的本地 production 输出。`/docs/customize/config/` 引用的本地 JavaScript 合计 **62,192 字节 gzip**，约 61 KiB，含 Lunr；两个样式表合计 **98,838 字节 gzip**，约 97 KiB。这是压缩文件测量，不包含字体、图片、搜索索引和第三方服务流量，不是浏览器总传输量或真实用户性能分数。

普通文档页未包含大型图表包。Mermaid 样本额外加载 **976,006 字节 gzip** 的 Mermaid 依赖，约 953 KiB，以及小型页面运行时。运行时隔离与输出检查通过。该依赖仍是图表页面的显著成本，本次并未缩减它，也未测量真实用户 Core Web Vitals。

## 限制与交付状态 {#limits}

无障碍套件沿用现有策略，排除上游 Redoc、Swagger UI 的 DOM；主题检查通过不代表这些第三方界面也获得认证。消费站点浏览器检查是抽样，并非完整矩阵。本地测试未认证线上站点、第三方服务的离线网络行为或真实设备性能。

保留了原有无关源码改动。生成文件、出版校验工具、日志和截图均位于忽略路径或仓库外。初次审查结束时，修复尚未提交；后续交付按主题与文档分批提交到本地 Git。此次交付不包含发布标签、升级消费版本、推送或部署。

---

反链：

- [研究](/zh/docs/design/research/)