# 长文渲染优化与压测报告

日期：2026-09-06。基线为 `750e172`，结果为本次未提交的渲染优化；基线和优化版使用相同样本、浏览器参数及操作序列。

## 1. 测试环境与范围

Windows、Intel Core i7-13620H、Headless Chrome 152，视口 1424 × 905，Vite 开发服务。每种规模重开测试页面三次，独立测试浏览器，不读写真实笔记。耗时基于 performance.now；打开指标不包含模块网络加载。样本含标题、表格、代码块、提示框和行内格式。

实际汉字数为 25632、61172、122322；Markdown 总字符数以原始 JSON 为准。不是仅以文件字节数代替“字数”。共完成优化前后 18 轮浏览器运行，所有运行的插入内容与文末完整性检查通过。

## 2. 本次优化

- 标题装饰按不可变文档和折叠状态弱缓存；光标移动不改变折叠状态时复用结果。没有折叠范围时不遍历全文生成隐藏装饰。
- 文档变更后用位置 Set 验证标题映射，避免对每个已折叠标题反复扫描所有标题。
- 字号装饰按不可变文档弱缓存；提示框标记位置按文档缓存，光标移动只判断标记是否处于编辑范围。
- 静态代码高亮增加 LRU，最多 64 项、累计 100 万个字符串字符；超过预算四分之一的单块不缓存。缓存同时包含深浅主题颜色，最终输出继续净化。缓存只在进程内，不写入存储。

弱缓存随文档释放，不用全局 Map 持有历史文档；高亮缓存有明确上限。

## 3. 对比结果

单位 ms。打开取三轮中位数；选区、插入、折叠取各轮 P95 的中位数；热预览取六次热运行中位数。P95 样本量较少，仅用于本机前后比较。

| 实际汉字数 | 打开 前→后 | 光标移动 P95 前→后 | 插入 P95 前→后 | 折叠/展开 P95 前→后 | 热预览 前→后 |
| --- | --- | --- | --- | --- | --- |
| 25632 | 272.1 → 218.6 | 1.9 → 0.6 | 7.0 → 6.9 | 55.0 → 45.6 | 40.0 → 26.6 |
| 61172 | 519.7 → 447.5 | 5.7 → 0.6 | 9.7 → 9.6 | 149.1 → 145.5 | 82.9 → 55.6 |
| 122322 | 875.4 → 869.1 | 11.9 → 1.2 | 22.2 → 27.2 | 256.6 → 263.9 | 140.2 → 95.5 |

主要收益是减少光标移动的重复工作，以及重复代码块/重复预览的高亮开销。2.5 万汉字样本完成全部操作，但不以此宣称所有文档都能维持 60 FPS。

12 万汉字的整篇折叠仍超过 250 ms，插入 P95 本轮反而增加，不能声称打字性能全面提升；全量 DOM 更新、编辑器自身处理与浏览器调度仍需进一步分项剖析。打开仍有长任务，缓存没有解决虚拟化问题。

## 4. 原始数据与复现

- [优化前 JSON](performance/2026-09-06-long-document-baseline.json)
- [优化后 JSON](performance/2026-09-06-long-document-after.json)
- [压测脚本与指标说明](../../frontend/tests/performance/README.md)

```powershell
npm --prefix frontend run test
npm --prefix frontend run build
npm --prefix frontend run dev -- --port 5175 --strictPort
# 另一个终端：
backend/.venv/Scripts/python.exe frontend/tests/performance/run-stress.py --url http://127.0.0.1:5175/tests/performance/stress.html --runs 3 --output .local-plans/stress-results.json
```

新增回归检查确认光标移动复用标题装饰、正文编辑使缓存失效、折叠与展开不残留隐藏内容。前端 402 项测试通过。

## 5. 边界与后续

本次测量是浏览器中的程序化编辑事务，不是输入法、实际键盘到屏幕显示、滚动帧率或生产包启动测试。样本代码块存在重复，LRU 收益不能直接外推到全部唯一代码块的文档。堆内存只采样，不作为内存泄漏结论。

后续应针对 12 万字的输入和整篇折叠采集独立 CPU trace，评估装饰的增量映射及可见区域渲染；在输入法、表格与代码块编辑验收之前，不直接给 contenteditable 应用跳过布局或整篇虚拟化。

## 6. 手动压测反馈后的滚动与定位修复

用户实测：2.56 万字正常，6 万字快速滚动轻微停顿，12 万字明显卡顿；从长文末尾全部折叠没有回到顶层。

本轮将“全部折叠”设为一次性把光标移到首个标题并将编辑区滚动到顶部，单个标题折叠保留原有定位行为。回归用例包含 100 个同级顶层标题，从文末触发后检查光标、scrollTop 与正文不变，避免只有一个 H1 的样本掩盖问题。

语言标签改为只同步变动的代码块，语言菜单只在打开时响应滚动定位，并合并同一帧的重复事件；监听祖先滚动，卸载时清理监听及待执行帧。

新增独立 CDP 滚轮测试，在相同的有限高度 flex 容器、纸间时光主题下，每档运行两次。下表为每次帧间隔 P95 的中位数，单位 ms，越小越好。这不是原先编辑事务基准的延续，也不是生产环境 FPS。

| 请求汉字数 | 修改前 | 修改后 |
| --- | ---: | ---: |
| 25000 | 30.05 | 20.10 |
| 60000 | 55.00 | 45.05 |
| 120000 | 90.10 | 100.00 |

两档较短样本有改善，12 万字没有改善，仍未达到流畅滚动的目标。CPU 采样显示滚入新代码块时的 CodeMirror 初始化、选区测量及 DOM 观察回调占用明显；不能仅凭此认定唯一原因。代码块布局隔离实验未带来收益，已撤回，未引入可能影响编辑、选区或布局的虚拟化。

- [滚轮基线数据](performance/2026-09-06-scroll-baseline.json)
- [滚轮修改后数据](performance/2026-09-06-scroll-after.json)

下一步需要评估代码块按交互初始化或编辑器级虚拟化，并同时验证输入、选区、搜索定位和折叠；当前不将 12 万字滚动问题标记为完成。

本轮前端 405 项测试通过，涵盖折叠定位、语言标签增量同步、菜单祖先滚动定位和卸载清理。

## 7. CodeMirror 高亮复用实验

在上轮提交 `874e916` 的基础上继续尝试：同一语言及主题的 CodeMirror LanguageSupport 内缓存高亮装饰，代码块离屏销毁后重新创建时，相同正文不再重复分词及构建装饰。缓存最多 32 项、64000 个源字符，超过 16000 字符的单块不缓存，使用 LRU 淘汰；语言支持释放时缓存一并释放。编辑后的内容按新正文计算，不复用旧位置。

回归测试通过统计分词调用验证跨视图复用、正文编辑重新计算和超限淘汰。原有深浅主题切换与编辑测试继续验证显示内容。

12 万字继续测量两次，帧间隔 P95 分别约 100.2 ms、90 ms，二者中位数约 95.1 ms；上一轮约 100 ms。样本重复代码较多，结果仍在明显波动范围内，不能宣称解决滚动卡顿。此优化减少确定可重复的高亮工作，但下一步仍须处理创建 CodeMirror 和布局测量的成本。

- [本轮滚轮原始数据](performance/2026-09-06-scroll-token-cache.json)

## 8. 主题对照与纸间时光 1.8.1 修复

用户补充：同一份 12 万字文档在默认浅色、深色下不卡顿。因此重新进行主题对照，之前将 CodeMirror 作为主要优化方向的判断不足；CPU 采样中的布局及选区测量耗时不能单独证明编辑器是主要原因。

保持相同文档和滚轮脚本，默认浅色、深色各测一次，P95 均约 30 ms。纸间时光 1.8.0 仅禁用整篇 `.ProseMirror` 的虚线 outline 后，两次 P95 约 30.1、30 ms；相比此前约 90–100 ms，构成明确的样式消融证据。主题与 CodeMirror 的交互仍可能影响布局，但不需要先用编辑器虚拟化解决这个差异。

修复将贯穿长文的虚线轮廓改为四条小尺寸渐变平铺背景，保留纸张、缝线、胶带、段落横线和叠纸阴影。独立伪元素虚线 border 的实验反而更慢，已撤回。正式主题版本升为 1.8.1。

| 主题或实验 | 次数 | 帧间隔 P95（ms） |
| --- | ---: | --- |
| 默认浅色 | 1 | 30 |
| 默认深色 | 1 | 30 |
| 1.8.0 仅禁用整篇 outline | 2 | 30.1、30 |
| 1.8.1 平铺缝线 | 3 | 30.1、30、30.1 |

1.8.1 三次测试的帧间隔中位数均为 10 ms，全部折叠后的 scrollTop 均为 0，光标位置均为 1。已检查视口截图，手账装饰保留。这里的结果说明本轮样本与环境下，纸间时光恢复到接近默认主题的滚动表现，不代表所有设备、所有复杂文档均无长任务。

已安装主题保存在本地，不会自动被新版资源覆盖。刷新前端后，到“主题 → 社区主题 → 纸间时光”点击“更新”，确认版本 1.8.1 再进行手动复测。

- [主题对比原始数据](performance/2026-09-06-scroll-theme-comparison.json)