在Alpine环境下Sphinx的Graphviz生成异常高图形问题求助

核心原因分析 #

这种高度异常放大的问题，本质是Graphviz在CI环境渲染时，因字体缺失或布局参数不一致，导致文本布局计算逻辑出错——更换版本无效说明不是版本兼容性问题，而是本地与CI的环境配置差异导致的渲染偏差。

具体解决方案 #

1. 强制指定Graphviz布局引擎与字体 #

在Sphinx的conf.py中添加或修改Graphviz参数，强制使用稳定的dot布局引擎，并指定CI环境中已安装的字体，避免因字体 fallback 引发布局计算错误：

graphviz_dot_args = [
    '-Kdot',  # 锁定dot布局引擎，避免CI环境默认使用其他引擎
    '-Tsvg',
    '-Nfontname="DejaVu Sans"',
    '-Efontname="DejaVu Sans"',
    '-Gfontname="DejaVu Sans"'
]

2. 在CI环境中安装必要字体 #

多数CI基础镜像默认缺少常用字体，这是Graphviz渲染异常的高频诱因。根据镜像系统添加字体安装步骤：

• Ubuntu/Debian系镜像：

apt-get update && apt-get install -y fonts-dejavu-core

• Alpine系镜像：

apk add --no-cache ttf-dejavu

3. 验证Graphviz环境一致性 #

在CI脚本中添加验证步骤，确保调用的dot可执行文件与本地版本、路径一致：

# 检查dot路径与版本
which dot
dot -V

4. 临时修复：批量修正SVG高度 #

如果上述方法暂时无法生效，可在Sphinx构建完成后用脚本批量修正异常SVG的高度参数：

import os
import re

# 遍历Sphinx构建后的HTML目录
svg_root = "_build/html"
for root, _, files in os.walk(svg_root):
    for file in files:
        if file.endswith(".svg"):
            svg_path = os.path.join(root, file)
            with open(svg_path, "r") as f:
                content = f.read()
            # 从viewBox中提取正确高度，替换异常的height属性
            viewBox_match = re.search(r'viewBox="0.00 0.00 \d+ (\d+\.\d+)"', content)
            if viewBox_match:
                correct_height = f'height="{viewBox_match.group(1)}pt"'
                content = re.sub(r'height="\d+pt"', correct_height, content)
                with open(svg_path, "w") as f:
                    f.write(content)

内容的提问来源于stack exchange，提问作者caxcaxcoatl