如何解决Mermaid流程图渲染模糊问题？

Question

在使用 Mermaid 生成流程图时，常因 SVG 渲染缩放或导出为 PNG 时分辨率不足导致图像模糊。尤其在高分屏或文档导出场景下，模糊问题尤为明显。该问题根源在于渲染容器尺寸未适配显示分辨率，或导出时未采用足够高的 DPI 设置。如何在不同平台（如 Markdown 预览器、Typora、VS Code 插件或网页集成）中确保 Mermaid 图表清晰显示，成为开发者和文档撰写者面临的常见痛点。需从 CSS 样式控制、SVG 缩放优化、导出配置调整等多方面综合解决。

Answer 1

1. 问题背景与现象分析

在使用 Mermaid 编写流程图、时序图等图表时，尽管其语法简洁且集成方便，但在高分辨率屏幕（如 Retina 屏）或导出为 PNG 等位图格式时，常出现图像模糊的问题。该现象广泛存在于 Markdown 预览器、Typora、VS Code 插件以及网页嵌入场景中。

根本原因在于：Mermaid 默认生成的 SVG 容器尺寸未根据设备像素比（devicePixelRatio）进行适配，导致渲染时像素映射失真；而在导出为 PNG 时，默认 DPI 设置偏低（通常为 96 DPI），无法满足高清输出需求。

例如，在 VS Code 的 Mermaid Preview 插件中，若未启用高清渲染选项，导出的 PNG 图像在放大查看时会出现明显锯齿和文字模糊。

2. 渲染机制与技术原理

Mermaid 图表默认以 SVG 形式渲染，SVG 是矢量图形，理论上可无限缩放而不失真。但实际显示效果受以下因素影响：

• CSS 尺寸控制：若容器被 CSS 强制缩放（如 transform: scale()），会引入插值算法导致模糊。
• 设备像素比（dpr）：现代高分屏 dpr 可达 2 或 3，若未按 dpr 提升 SVG 内部分辨率，则渲染后等效 DPI 不足。
• 导出流程中的光栅化步骤：将 SVG 转为 PNG 时，若未设置高分辨率画布，会导致信息丢失。

// 示例：获取设备像素比
const dpr = window.devicePixelRatio || 1;
console.log(`当前设备像素比：${dpr}`);

3. 平台差异与典型表现

平台	模糊表现	是否支持高清导出	配置方式
Typora	预览清晰，导出 PNG 模糊	需手动开启“高分辨率导出”	偏好设置 → 导出 → 高 DPI
VS Code + Mermaid Preview	缩放后文字发虚	支持，需配置 exportQuality	settings.json 中设置 mermaid.preview.exportScale
网页集成（mermaid.js）	响应式缩放失真	可通过 JS 控制	初始化时配置 scale 参数

4. 解决方案一：CSS 样式优化

避免使用 transform: scale() 直接缩放 SVG 容器。推荐通过设置固定宽高并结合 viewBox 实现响应式布局。

.mermaid svg {
  width: auto !important;
  height: auto !important;
  min-width: 100%;
  max-width: 100%;
}

同时，在高分屏下可利用媒体查询提升渲染精度：

@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .mermaid svg {
    image-rendering: -webkit-optimize-contrast;
    image-rendering: crisp-edges;
  }
}

5. 解决方案二：SVG 缩放与分辨率适配

在网页中集成 Mermaid 时，可通过 JavaScript 动态调整图表缩放比例，适配 devicePixelRatio。

mermaid.initialize({
  startOnLoad: true,
  securityLevel: 'loose',
  theme: 'default',
  flowchart: {
    useMaxWidth: true,
    htmlLabels: true,
    curve: 'cardinal'
  },
  // 关键配置：提升缩放质量
  scale: window.devicePixelRatio || 1
});

6. 解决方案三：导出配置优化

在 Typora 或 VS Code 中导出 PNG 时，应确保启用高 DPI 输出模式。以 VS Code 为例，在 settings.json 中添加：

{
  "mermaid.preview.exportScale": 2,
  "mermaid.preview.theme": "default"
}

对于命令行导出工具（如 mermaid-cli），可通过指定 dpi 参数提升清晰度：

mmdc -i input.mmd -o output.png -w 1000 -H 800 --dpi 192

7. 综合实践：构建高清 Mermaid 输出流程

1. 在文档写作阶段，使用原生 Mermaid 语法编写图表。
2. 集成时通过 JS 初始化配置，启用高缩放因子。
3. 应用上述 CSS 规则防止浏览器自动模糊处理。
4. 导出前检查平台是否支持高 DPI 输出。
5. 优先导出为 SVG 格式用于印刷或网页发布。
6. 必须使用 PNG 时，设置 dpi ≥ 192。
7. 验证输出图像在 200% 缩放下仍保持清晰可读。

8. 可视化示例：Mermaid 渲染优化流程图

graph TD
    A[编写 Mermaid 代码] --> B{发布场景?}
    B -->|网页嵌入| C[初始化配置 scale=dpr]
    B -->|文档导出| D[启用高 DPI 导出选项]
    C --> E[应用防模糊 CSS]
    D --> F[导出为 SVG/PNG @2x~3x]
    E --> G[测试多屏显示效果]
    F --> G
    G --> H[确认文字边缘清晰无锯齿]

9. 进阶建议与长期维护策略

对于企业级文档系统，建议建立统一的 Mermaid 渲染规范，包含：

• 强制使用最新版 mermaid.js（≥ v10.x），支持更好的高清渲染。
• 封装自定义导出脚本，自动检测环境并设置最佳 dpi。
• 在 CI/CD 流程中加入图像质量检测步骤。
• 提供内部培训材料，说明如何识别和修复模糊图表。

此外，可监控 GitHub 上 mermaid-js 官方仓库的 export-enhancement 类 issue，及时跟进社区解决方案。