SVG文字消失之谜：Mermaid渲染服务的字体依赖陷阱

引言：当“有效SVG”变成“隐形图表”

一位开发者构建了Mermaid转图片的API服务，支持将流程图、时序图、类图等转换为PNG或SVG格式，并以base64编码返回，方便AI代理生成可分享的图片。测试阶段一切正常，但真实用户却发来截图：本该显示图表的地方，只有一片空白。

问题只出现在SVG输出上。PNG完全正常，SVG文件本身是合法的XML，在浏览器中打开却什么也看不到。经过排查，罪魁祸首浮出水面：Mermaid的SVG输出会把文字嵌入为<text>元素，并指定一个在渲染服务器上并不存在的字体。浏览器会回退到备用字体，所以你能看到文字；但Slack、Discord、GitHub预览等大多数消费端不会回退——它们忠实执行缺失的字体，结果就是什么都不渲染。文字就在DOM里，只是“隐形”了。

问题根源：字体依赖的两种契约

PNG与SVG的本质差异

这位开发者将问题归结为一种被忽视的契约差异：服务端渲染图片时，你交付的不只是像素，还有字体依赖。

PNG在渲染时就把文字栅格化成像素，字体只需要存在于你的服务器上。而SVG保留文字为文本，这意味着字体必须存在于每一台显示它的设备上。这听起来是细节，却直接决定了输出结果在真实世界中的可见性。

SVG的文字渲染与字体回退机制

SVG是一种基于XML的矢量图形格式，其文字通过<text>元素描述，并借助font-family属性引用字体。与位图不同，SVG本身不包含字体数据（除非使用@font-face嵌入或文字转路径），因此渲染结果高度依赖显示环境。浏览器通常会实现字体回退：当指定字体缺失时，按font-family列表依次尝试，最终使用系统默认字体，从而保证文字可见。但许多非浏览器消费端（如聊天软件预览、代码托管平台的Markdown渲染器、邮件客户端）为了性能或安全，往往采用简化的SVG渲染引擎，可能不支持字体回退，甚至直接忽略缺失字体的文字元素。这就是为什么同一份SVG在浏览器中正常，在其他平台却“隐形”。理解这一差异，有助于在设计服务端渲染API时，主动选择更可靠的输出策略。

具体的触发条件

问题之所以隐蔽，是因为开发者的环境掩盖了它。渲染服务器使用无头Chromium，并配置了--font-render-hinting=none参数，运行在一个极简容器镜像中——该镜像没有安装任何字体。同时，Mermaid默认将font-family设置为"trebuchet ms", verdana, sans-serif，这些字体在服务器上均不存在。

在浏览器里测试时，浏览器自动替换了字体，一切看起来正常。但一旦SVG文件被发送到Slack、Discord、GitHub评论、Notion或邮件客户端，这些平台不会做字体回退，缺失字体的文字直接不可见。开发者花了三天时间，渲染出的图表“没有人能看到”。

无头浏览器与字体渲染参数

无头Chromium是在无图形界面环境下运行Chromium的浏览器模式，常用于服务端自动化渲染、截图和PDF生成。它默认会加载系统字体，但容器镜像通常为了减小体积而不预装字体包。--font-render-hinting=none参数用于关闭字体微调（hinting），使渲染结果在不同平台上更一致，但它并不解决字体缺失问题。当页面指定的字体不存在时，无头浏览器可能回退到默认字体或直接不渲染文字，具体行为取决于版本和配置。开发者容易在本地开发环境（通常装有丰富字体）中测试通过，而部署到精简容器后出现文字缺失。因此，在容器中显式安装所需字体，并在渲染配置中指定实际存在的字体栈，是保证输出可靠性的关键步骤。

修复方案与工程启示

两行Dockerfile的修复

解决方案出奇简单：在Dockerfile中安装fonts-dejavu-core，并将Mermaid的fontFamily设置为服务器上真实存在的字体栈（DejaVu Sans, sans-serif），而不是默认的"trebuchet ms", verdana, sans-serif。修改后，SVG输出在Slack、Discord、Notion、GitHub评论和邮件客户端中均渲染一致。

fonts-dejavu-core 与字体栈设计

fonts-dejavu-core是Debian/Ubuntu系Linux发行版中的一个基础字体包，包含DejaVu Sans、DejaVu Serif和DejaVu Sans Mono等字体，覆盖拉丁、希腊、西里尔字母及常用符号，体积小且开源，常被用作容器环境的最小字体集。安装后，需在Mermaid配置中将fontFamily显式设置为"DejaVu Sans, sans-serif"，确保渲染器优先使用已安装的字体，并以通用sans-serif作为最终回退。这样生成的SVG中font-family属性引用的字体在服务器和大多数消费端都更可能可用，从而减少“隐形文字”风险。对于需要多语言支持的服务，还应考虑安装更全面的字体包（如fonts-noto-cjk），并在文档中说明字体依赖。

设计决策的调整

修复之后，这位开发者将新用户的默认输出改为PNG，并把SVG改为需要主动选择的功能，同时在文档中加入了警告。这个决策值得借鉴：对于需要广泛分享的图表，PNG的“字体自包含”特性降低了跨平台风险；SVG虽然更灵活，但必须明确告知使用者字体依赖的存在。

测试策略的反思

文章最后给出了一条普遍适用的建议：如果你在构建任何图片或图表渲染API，要在输出实际被消费的地方测试，而不只是在开发机的浏览器里。浏览器的容错性会掩盖问题，而真实消费端往往更严格。“有效SVG”和“可见图表”不是一回事。

对AI代理工具开发的启示

这个案例对当前快速增长的AI代理工具生态有直接参考价值。当AI代理生成图表、报告或可视化内容并交付给用户时，输出格式的选择会直接影响可用性。开发者最终将服务打包为x402.freeq.one，支持流程图、时序图、类图和甘特图，一次调用返回PNG或SVG的base64数据。

对于构建类似服务的团队，有三点可以落地：

• 默认使用PNG，除非用户明确需要矢量可编辑性。
• 严格安装字体，并在渲染配置中显式指定字体栈。
• 在目标消费环境做验收，把Slack、Discord、GitHub等平台纳入测试范围。

字体看似是渲染管线的末端细节，实际上决定了服务端生成的图片能否真正被看见。