mermaid中文版渲染乱码如何解决？

Question

在使用 Mermaid 中文版时，常出现流程图或时序图中的中文文字显示为乱码或方框的问题。该问题主要源于渲染环境（如浏览器、Markdown 预览器或静态站点生成器）未正确加载支持中文的字体，或未设置 UTF-8 字符编码。尤其在导出 SVG 或 PNG 图像时，若后端渲染服务（如 Puppeteer 或 Playwright）缺少中文字体依赖，中文将无法正常显示。此外，部分 Mermaid 版本对非 ASCII 字符处理不完善，也会导致渲染异常。如何在不同部署环境下确保中文字体可用并正确配置字符集，是解决 Mermaid 中文乱码的关键技术挑战。

Answer 1

1. 问题背景与现象描述

在使用 Mermaid 中文版绘制流程图、时序图或类图时，开发者常遇到中文显示为乱码或方框（□）的现象。该问题广泛存在于多种技术场景中，包括但不限于：

• 浏览器直接渲染 Markdown 文件中的 Mermaid 图表
• 静态站点生成器（如 Hugo、VuePress、Docusaurus）构建文档时导出图像
• 通过 Puppeteer 或 Playwright 后端服务将 Mermaid 脚本转为 SVG/PNG
• CI/CD 环境下自动化生成技术文档

根本原因在于：文本编码未统一为 UTF-8、CSS 字体栈未包含中文字体、或服务器环境缺失中文字体文件。

2. 技术成因分层解析

层级	影响因素	典型表现
字符编码	HTML/Mermaid 源码未声明 UTF-8	所有非 ASCII 字符异常
前端样式	CSS 字体族不支持中文	浏览器 fallback 到无中文覆盖的字体
运行时环境	Puppeteer 无中文字体依赖	导出图片时中文变方框
Mermaid 版本	v8 及以下对 Unicode 处理缺陷	特定符号截断或渲染失败

3. 解决方案路径图谱

graph TD
  A[Mermaid 中文乱码] --> B{环境类型}
  B --> C[前端浏览器]
  B --> D[后端渲染服务]
  C --> E[设置 UTF-8 编码]
  C --> F[注入中文字体 CSS]
  D --> G[安装系统级中文字体]
  D --> H[配置 Puppeteer 字体路径]
  D --> I[升级至 Mermaid v10+]

4. 前端层面修复策略

确保 HTML 页面正确声明字符集：

<meta charset="UTF-8">

并通过 CSS 显式指定支持中文的字体栈：

.mermaid {
  font-family: "Microsoft YaHei", "SimSun", "Hiragino Sans GB", sans-serif;
}

若使用 VuePress 或 Docusaurus，可在 override.css 中全局注入上述样式规则。

5. 后端渲染服务字体配置

当使用 Node.js + Puppeteer 进行无头浏览器截图时，需确保操作系统已安装常见中文字体。以 Ubuntu 为例：

sudo apt-get install -y fonts-wqy-zenhei \
                        fonts-wqy-microhei \
                        ttf-mscorefonts-installer
sudo fc-cache -fv

验证字体是否生效：

fc-list :lang=zh

6. Mermaid 配置项优化建议

在初始化 Mermaid 实例时，显式设置主题配置以增强字体兼容性：

mermaid.initialize({
  theme: 'default',
  fontFamily: 'Arial, Microsoft YaHei, SimSun, sans-serif',
  securityLevel: 'loose',
  flowchart: { useMaxWidth: true }
});

推荐升级至 Mermaid v10 或更高版本，其内部对 Unicode 和 SVG text 渲染有显著改进。

7. CI/CD 自动化部署实践

在 GitHub Actions 或 GitLab CI 中集成字体预装步骤：

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Install Chinese Fonts
        run: |
          sudo apt-get update
          sudo apt-get install -y fonts-arphic-ukai
          sudo fc-cache -fv
      - name: Build Site
        run: npm run build

此方式可保障每次构建环境的一致性，避免“本地正常、线上异常”问题。

8. 跨平台兼容性测试方法论

建立多环境验证矩阵：

平台	字体支持	编码检测工具
Windows	微软雅黑内置	Notepad++ 编码查看
macOS	PingFang SC 默认	file -I 命令行
Linux Docker	需手动安装	chardetect Python 工具

9. 监控与诊断工具链整合

引入自动化检测脚本，在构建阶段识别潜在乱码风险：

#!/bin/bash
if ! grep -q "charset=utf-8" index.html; then
  echo "⚠️ Missing UTF-8 declaration"
  exit 1
fi

if ! fc-list | grep -i "yahei\|song\|kai"; then
  echo "❌ No Chinese font found in system"
  exit 1
fi

结合 Lighthouse 审计或自定义 Puppeteer 测试用例，实现持续质量保障。

10. 未来演进方向与生态协同

随着 Web Components 和 WASM 技术在图表渲染领域的渗透，Mermaid 团队正在探索将字体子集嵌入 SVG 输出的能力。社区已有提案提议通过 @font-face 内联 Base64 编码的精简版思源黑体，从根本上规避外部依赖。同时，主流静态站点框架也开始默认启用 UTF-8 输出编码，逐步减少此类国际化问题的发生概率。