Matplotlib AGG后端在无屏Web应用中轴标签显示异常问题

这种跨环境的渲染差异我碰到过好几次，核心问题大多和字体配置或者无屏环境的渲染上下文缺失有关——毕竟Windows带GUI的环境默认有完善的字体和渲染支持，而无屏Ubuntu服务器通常没预装Matplotlib需要的字体，也缺少必要的底层渲染依赖。下面是我亲测有效的解决步骤：

1. 检查并安装缺失的系统字体 #

Matplotlib的AGG后端依赖系统字体渲染文字，无屏Ubuntu默认可能没有预装常用的无衬线字体，直接导致文字渲染混乱：

• 先查看当前Matplotlib能识别的系统字体：

  import matplotlib.font_manager
  print(matplotlib.font_manager.findSystemFonts())
  

  如果输出里没有Arial、Noto Sans这类通用无衬线字体，就需要安装系统字体包：

  sudo apt install fonts-noto-core
  

• 安装完成后，清除Matplotlib的字体缓存，让它重新识别新字体：

  rm -rf ~/.cache/matplotlib/
  

  之后重启你的Django服务。

2. 显式指定Matplotlib渲染字体 #

就算安装了字体，AGG后端有时也不会自动选择合适的，建议在代码里强制指定字体：

import matplotlib
matplotlib.use('agg')
import matplotlib.pyplot as plt

# 全局设置字体和字号，避免文字过小/重叠
plt.rcParams['font.family'] = 'Noto Sans'
plt.rcParams['font.size'] = 10

# 正常绘制图表
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [4, 5, 6])
ax.set_xlabel('X轴标签')
ax.set_ylabel('Y轴标签')
# 其他绘图逻辑...

3. 手动调整图表布局间距 #

无屏环境下AGG的布局计算可能和GUI环境略有差异，需要给轴标签留出足够空间：

• 最简单的方法是用tight_layout()自动调整：

  plt.tight_layout()
  

• 如果自动布局效果不好，也可以手动设置边距：

  fig.subplots_adjust(left=0.15, right=0.9, bottom=0.15, top=0.9)
  

4. 检查并安装底层渲染依赖 #

AGG后端依赖freetype和libpng库来渲染文字和图片，确保Ubuntu环境安装了这些依赖：

sudo apt install libfreetype6-dev libpng-dev

安装完成后，建议重新安装Matplotlib，确保它编译时链接了这些库：

pip install --force-reinstall matplotlib

修改完这些配置后，重新生成图表应该就能和Windows环境下的输出一致了。

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