让技术文档中的流程图和数据图真正可读：Mermaid 与 ECharts 实战

流程图适合解释状态与责任边界，数据图适合展示数值变化。它们不是截图的替代皮肤：图表必须有可审阅的源文本、数据含义、失败回退和移动端布局，才能长期维护。

什么时候选哪一种

• Mermaid：流程、时序、状态和依赖关系；文本和文章一起版本管理，差异容易审查。
• ECharts：柱线饼图、坐标轴、图例和交互提示；数据应与展示配置分开，避免把业务结果硬编码到主题样式里。
• 图片：复杂视觉或已有设计稿，但要附替代文本、数据来源和更新时间；不要把图片当作唯一解释。

同一张图不要承担“流程 + 统计 + 权限 + 部署”所有问题。拆成小图并在正文解释判断条件；节点和边数量也要设置上限，避免超大图拖垮页面。

Mermaid 安全和版本

公开文章、访客投稿和从外站导入的代码块都属于不可信输入。使用安全级别严格的默认配置，不开放图中任意 HTML、脚本或点击回调；只允许站点需要的图类型和有限文本长度。不要因为某个图需要链接就把全站切换到宽松策略。Mermaid 的安全配置随主版本调整，升级时应对照实际锁定版本的文档，并做攻击样例回归。

Markdown 编辑预览和公开阅读最好调用同一渲染实现，防止后台看起来安全、发布后却按另一套规则执行。无法识别或解析失败时保留源码、标题与错误说明，不要整篇文章白屏。

ECharts 生命周期与响应式

图表容器必须先有稳定高度，再初始化。窗口变化不一定等于容器变化：侧栏展开、标签切换和移动端布局都可能改变容器尺寸，因此用 ResizeObserver 观察容器，调用实例 resize。容器被卸载或文章路由切换时 disconnect observer 并 dispose 图表实例；只隐藏容器而不释放实例会累积监听和 Canvas。

配置由 JSON 解析，不用 eval 执行作者脚本。限制 JSON 字节数、数组长度、series 数量、点数、轴标签长度和允许的图表类型；对于颜色、tooltip formatter、symbol 等可放函数的字段，不接受任意函数。错误图表显示诊断提示并保留原始配置供作者修改。

无障碍与移动端

每幅图至少提供一句结论、数据来源/时间范围和单位说明；关键数值在正文、表格或摘要里再出现一次。配色不能只用颜色表达正负，文本标签与对比度需可读。手机窄屏下检查轴标签截断、图例换行、横向滚动和触控提示；不应以拖动图表才能读到全部内容作为唯一方案。

上线清单

1. 普通文章不加载 Mermaid/ECharts；命中对应代码块后才下载渲染包。
2. 在 Chromium、Safari/iOS 和窄视口验证字体、尺寸、深浅主题与长标题。
3. 用无效语法、超大输入、恶意 HTML、超多数据点验证错误边界和渲染上限。
4. 文章切换、目录展开、字体加载完成和容器尺寸改变后，检查图表是否重排且没有重复实例。
5. 禁用 JavaScript 时仍保留图表说明和数据摘要。

源码与渲染策略

保存代码块时保留 Mermaid 源文本，不把它预先变成不可编辑的 SVG。阅读端在图表进入视口后创建临时渲染容器，路由切换时清理容器、图表实例和观察器。ECharts 使用独立 option 和实例；暗色主题变化时更新或重建实例，并验证 ResizeObserver 已释放。服务端先输出源码、标题和说明，客户端增强成功后再显示图形，避免 SSR 与水合阶段输出不一致。

动态图表还要明确数据时间戳、单位、缺失值和聚合方式。图例开关不应改变底层数据口径；切换筛选时同步更新图旁的文字摘要。长列表优先提供表格或下载数据，避免将图形本身当成唯一数据出口。测试 SVG 导出时也要确认标题、替代文本与来源保留。

参考：Mermaid 安全说明、Mermaid 使用和安全级别、ECharts 图表容器尺寸与销毁。