Python Matplotlib绘图中文乱码怎么解决

在使用 Python 的 Matplotlib 库绘制图表时，如果在标题、坐标轴标签或图例中包含中文，默认情况下图表往往会出现白色方块（“豆腐块”）、问号或抛出 UserWarning: Glyph missing from current font 警告。解决这一问题的核心非常直接：通过配置指定支持中文的系统字体，并设置正确显示负号。本文将系统梳理乱码根源、两套主流配置方法，以及字体缓存导致的异常排查技巧。

一、为什么会出现中文方块与乱码

Matplotlib 在初始化时会加载默认配置文件，其默认英文字体族为 sans-serif，首选字体通常是 DejaVu Sans。该字体库仅覆盖常用的 ASCII 字符、西欧字符以及部分数学符号，并未打包中文字形数据。当渲染引擎尝试在字库中寻找汉字字形（Glyph）失败时，便会回退并绘制占位空心矩形。

此外，当我们将字体替换为中文字体后，常常还会遇到负号（-）显示为异常方块的问题。这是因为某些中文字库中减号与 ASCII 连字符码位不同，需要同时关闭 Unicode 负号渲染回退。

图 1：Matplotlib 默认文本渲染机制与中文字形缺失排查示意图

二、主流操作系统可用中文字体名称

配置字体时，必须填入当前操作系统中实际安装的字体名称。不同操作系统自带的中文字体家族名称有所差异，常见对应关系如下：

• Windows 系统：SimHei（黑体）、Microsoft YaHei（微软雅黑）、SimSun（宋体）、KaiTi（楷体）。
• macOS 系统：Arial Unicode MS、PingFang SC（苹方）、Heiti SC（黑体-简）、STHeiti。
• Linux 系统（Ubuntu/Debian/CentOS）：系统通常默认无中文字体，需预先安装中文字体包，如 WenQuanYi Micro Hei（文泉驿微米黑）或 Noto Sans CJK SC（思源黑体）。

三、方法一：修改全局 rcParams 参数（最推荐）

这是最省心、最通用的解决方案。在导入 Matplotlib 之后，只需添加两行全局参数设置，后续所有图表元素的标题、图例、坐标轴文本均会自动套用该字体设置，无需逐一修改绘图函数。

import matplotlib.pyplot as plt

# 1. 设置中文字体（以 Windows 上的 SimHei 为例，macOS 可换为 'Arial Unicode MS' 或 'PingFang SC'）
plt.rcParams['font.sans-serif'] = ['SimHei']

# 2. 正常显示负号（解决坐标轴负数符号乱码问题）
plt.rcParams['axes.unicode_minus'] = False

# 绘制测试图表
plt.figure(figsize=(6, 4))
plt.plot([1, 2, 3], [-2, 5, 3], marker='o')
plt.title("月份销量与利润趋势")
plt.xlabel("季度周期")
plt.ylabel("利润额（万元）")
plt.show()

图 2：rcParams 全局中文字体配置具体操作步骤流程

四、方法二：使用 FontProperties 局部加载指定字体

如果当前开发环境没有管理员权限，无法在操作系统中注册字体，或者需要使用特定本地 TTF/OTF 字体文件，可以使用 matplotlib.font_manager.FontProperties 进行按需指定。此方法不会改变全局字体环境，仅对传入了字体的对应文本有效。

import matplotlib.pyplot as plt
from matplotlib.font_manager import FontProperties

# 指定本地字体文件路径（支持 .ttf 或 .otf 格式）
my_font = FontProperties(fname='/path/to/custom_font.ttf')

plt.figure(figsize=(6, 4))
plt.plot([1, 2, 3], [4, 5, 6])

# 在需要中文的位置传入 fontproperties 参数
plt.title("局部加载中文字体示例", fontproperties=my_font)
plt.xlabel("横轴名称", fontproperties=my_font)
plt.ylabel("纵轴名称", fontproperties=my_font)
plt.show()

图 3：两种解决中文乱码方案的特征对比与技术选型

五、常见问题与字体缓存清理

很多开发者在安装了中文字体或修改了配置后，仍然发现提示 findfont: Font family ['SimHei'] not found。这是由于 Matplotlib 会在初次启动时将系统已发现的字体索引写入磁盘缓存文件，若字体是在缓存生成后安装的，或者配置路径发生变动，引擎无法感知新字体。

排查和解决该问题的标准步骤包括两步：

1. 查看当前缓存目录：在 Python 中执行以下命令打印缓存文件所在路径：

   import matplotlib
   print(matplotlib.get_cachedir())

2. 清除字体缓存文件：关闭当前 Python 运行环境，进入上述输出的目录，删除名称类似于 fontlist-v330.json（数字版本号可能因 Matplotlib 版本不同而变化）的缓存文件。重新运行脚本时，Matplotlib 将重新扫描系统字体并建立最新的字库索引。

图 4：Matplotlib 中文显示问题排查完整方案决策总结