D2 如何用 --font-regular 等参数在渲染时替换 TTF 字体？

D2 如何用 --font-regular 等参数在渲染时替换 TTF 字体？

【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2

D2 在渲染图表时默认使用内置字体（普通、斜体、粗体、中粗体来自 Source Sans Pro，等宽字体来自 Source Code Pro）。如果你希望导出结果使用自己的字体文件，可以在执行d2渲染命令时通过--font-regular、--font-bold等参数传入.ttf文件路径。本文基于 D2 仓库中的 CLI 参数定义、man 页和 CLI E2E 测试，说明如何完成这次字体替换，以及如何判断替换确实生效。

前提条件：已安装可执行的d2CLI，且手头有要使用的.ttf字体文件。参数帮助明确说明传入的应是.ttf文件路径。

可用的字体参数及其默认值

d2cli/main.go 中定义了 8 个字体参数，man 页模板 给出了完整说明。每个参数只替换一种字体槽位，作用互不干扰：

参数是逐个独立加载的：loadFonts（d2cli/main.go#L1117）只对非空的参数读取对应 TTF 文件。也就是说，只传--font-bold时只有粗体被替换，其余槽位仍用默认字体；一个都不传时则完全不加载自定义字体。

用自定义字体渲染一张图表

仓库的 CLI E2E 测试with-font（e2etests-cli/main_test.go#L344-L358）演示了完整流程。测试先写入一个 D2 源文件，然后带--font-bold参数执行渲染。可以照此操作：

1. 准备一个 D2 源文件font.d2，测试中使用的内容是：

a: Why do computers get sick often? b: Because their Windows are always open! a -> b: italic font

2. 把你的 TTF 文件放在工作目录下（仓库自带的测试字体是 e2etests-cli/RockSalt-Regular.ttf），然后执行渲染。下面的命令中./RockSalt-Regular.ttf为测试使用的字体路径，换成你自己的 TTF 相对路径即可：

d2 --font-bold=./RockSalt-Regular.ttf font.d2

未指定输出路径时，d2默认写出与输入同名的font.svg。测试断言命令成功（assert.Success），并且读出的font.svg与黄金文件 with-font.exp.svg 一致，这就是该命令的预期结果。

如果需要同时替换多种字体，各参数并列传入即可，例如：

d2 --font-regular=./regular.ttf --font-italic=./italic.ttf --font-bold=./bold.ttf font.d2

不想在命令行重复书写时，man 页说明这些 flag 也可以用对应环境变量设置（如D2_FONT_REGULAR、D2_FONT_BOLD、D2_FONT_MONO等），效果相同。

验证替换是否生效

两点依据，均来自仓库文档：

1. 看退出状态而不是只看输出文件。man 页明确指出：不要因为输出文件存在就认为渲染成功，应以d2的退出状态为准——渲染出错时 D2 有时仍会写出部分渲染结果。
2. 检查 SVG 中嵌入的@font-face。生成 SVG 时，D2 会把使用的字体以@font-face规则内嵌，字体族名由图表哈希加后缀构成，例如d2-<hash>-font-regular、d2-<hash>-font-bold。嵌入逻辑见 d2svg 字体嵌入实现。docs/examples/vector-grid/vector-grid.svg 是一份现成的输出示例，其中包含：

font-family: "d2-1314486588-font-regular"; @font-face { font-family: d2-1314486588-font-regular;

（以上为文档示例，实际哈希值随图表内容变化。）替换后打开生成的 SVG，确认font-bold槽位对应的@font-face指向你的字体子集，即说明自定义字体已被内嵌使用。

可选分支：d2.js 中的字体选项

如果渲染走的是 D2 的 JavaScript/WASM 封装而不是 CLI，d2js/js/README.md 中CompileOptions提供对应的字体选项：fontRegular、fontItalic、fontBold、fontSemibold，取值是包含.ttf内容的字节数组（byte array），不提供时使用与 CLI 相同的默认字体。注意该 API 文档只列出这 4 个常规字体选项，没有等宽字体选项，且是传字体内容而非文件路径，与 CLI 的用法不通用。

边界与限制

• 参数只接受.ttf文件路径（参数帮助原文：path to .ttf file），文件不存在或读取失败时loadFonts会返回错误，渲染不完成。
• 每个参数只影响一种字重/风格槽位；文档未说明某个参数会连带替换其他槽位。
• 未传任何字体参数时不会加载自定义字体，全部使用内置默认字体。

下一步：若替换字体后布局或字号表现异常，可结合-d打印调试日志定位（man 页--debug说明）。

【免费下载链接】d2D2 is a modern diagram scripting language that turns text to diagrams.项目地址: https://gitcode.com/GitHub_Trending/d2/d2