解决Python画图中文乱码:matplotlib字体配置方法
全面解析Python使用matplotlib画图时出现中文乱码与负号方块的原因,详细介绍rcParams动态配置、matplotlibrc全局配置及FontProperties局部指定三种实用解决方案。
在使用 Python 的 Matplotlib 库绘制图表时,标题、坐标轴标签或图例中的中文字符经常会变成一个个空白小方块(俗称“豆腐块”),控制台还会弹出大量 Glyph missing 警告;同时负号也常被误显示为乱码方框。要彻底解决该问题,核心在于告知 Matplotlib 正确的中文字体回退列表,并关闭 Unicode 减号的 ASCII 替换机制。本文将系统阐述乱码成因,并提供动态脚本配置、全局环境配置与局部显式指定三种实用方法。
一、为什么会出现中文方块与负号乱码
Matplotlib 默认采用的西文字体是 DejaVu Sans。该字体设计之初仅包含了西欧字符集的字形映射表(Glyph Table),并未收录 CJK(中日韩)汉字编码。当绘图引擎遍历渲染文本中的中文字符时,在字体文件的字符索引表中无法找到对应的矢量轮廓,只能使用字库中的默认缺省符号(一个空心矩形方框)进行占位。
此外,坐标轴数值上的负号之所以也会变成方块,是因为 Matplotlib 默认开启了 axes.unicode_minus = True。在此配置下,减号会使用标准的 Unicode 字符 U+2212 (MINUS SIGN) 进行排版,而许多常用中文字体仅支持标准 ASCII 码的破折号/减号 U+002D (HYPHEN-MINUS),进而再次引发字形缺失。
二、方法一:脚本级动态配置(推荐常规使用)
动态配置是日常数据探索与单脚本开发中最常用的方式。通过在导入 matplotlib.pyplot 之后修改全局参数字典 plt.rcParams,即可在当前运行时生效,不影响系统其他程序。
1. 跨平台兼容代码模板
由于 Windows、macOS 与 Linux 系统内置的中文字体名称各不相同,推荐在 font.sans-serif 中传入一个有序列表。Matplotlib 会按照从前到后的顺序逐一查找,直到找到本机已安装的可用字体:
import matplotlib.pyplot as plt
import numpy as np
# 1. 设置无衬线字体回退顺序(适配 Windows、macOS 与 Linux)
plt.rcParams['font.sans-serif'] = [
'PingFang SC', # macOS 常用黑体
'Microsoft YaHei', # Windows 微软雅黑
'SimHei', # Windows 黑体
'WenQuanYi Micro Hei', # Linux 文泉驿微米黑
'sans-serif' # 默认保底无衬线字体
]
# 2. 正常显示负号(关键:避免负号被渲染为方块)
plt.rcParams['axes.unicode_minus'] = False
# 测试绘图
x = np.linspace(-5, 5, 100)
y = np.sin(x)
plt.figure(figsize=(8, 4.5))
plt.plot(x, y, label='正弦波动曲线', color='#486581', linewidth=2)
plt.title('正弦函数在区间 [-5, 5] 的取值走势')
plt.xlabel('横坐标(包含负数区间)')
plt.ylabel('函数输出值')
plt.grid(True, linestyle='--', alpha=0.6)
plt.legend()
plt.show()
DejaVu Sans 放在首位,Matplotlib 找到该字体后就会停止回退,导致中文依然无法正确解析。
三、方法二:全局永久配置(一劳永逸)
若每次新建脚本都编写 rcParams 显得冗余,可通过修改 Matplotlib 的配置文件 matplotlibrc 并配合安装字体文件,实现系统级默认支持中文。
详细操作说明
-
获取配置与字体目录:
在终端或交互环境中运行以下代码:
import matplotlib print("字体存放目录:", matplotlib.get_data_path() + '/fonts/ttf') print("缓存目录:", matplotlib.get_cachedir()) print("用户配置文件路径:", matplotlib.matplotlib_fname()) -
放入字体文件:
下载或从系统字体库(如 Windows 的
C:\Windows\Fonts\simhei.ttf)中拷贝字体至上述的fonts/ttf文件夹下。 -
修改
matplotlibrc文件: 使用文本编辑器打开matplotlib.matplotlib_fname()所指向的文件,找到并去除以下三项前面的#注释,修改为:font.family : sans-serif font.sans-serif : SimHei, DejaVu Sans axes.unicode_minus : False -
删除旧缓存文件:
Matplotlib 会在本地缓存中建立字体索引树(通常为
~/.cache/matplotlib/fontlist-v***.json)。若不清理该文件,Matplotlib 仍会读取旧索引而无法识别新拷入的字体。删除该目录下的缓存文件后重启 Python,系统会自动重新扫描并重建缓存。
四、方法三:FontProperties 局部精确控制
当处于没有系统管理员权限的服务器、或者只需要在某些特定图表元素中使用定制中文字体时,使用 FontProperties 是最精确且不产生全局副作用的选择。它允许直接传入本地任意路径的 .ttf 或 .otf 字体文件。
import matplotlib.pyplot as plt
from matplotlib.font_manager import FontProperties
# 直接通过字体文件绝对路径或相对路径实例化
# 例如指定本地的字体文件路径
my_font = FontProperties(fname='/System/Library/Fonts/PingFang.ttc', size=12)
title_font = FontProperties(fname='/System/Library/Fonts/PingFang.ttc', size=16, weight='bold')
plt.figure(figsize=(7, 4))
plt.plot([1, 2, 3], [4, 5, 2], marker='o', color='#71A397')
# 在需要输出中文的地方显式指定 fontproperties 参数
plt.title('通过 FontProperties 局部定制字体', fontproperties=title_font)
plt.xlabel('采样周期(天)', fontproperties=my_font)
plt.ylabel('数值指标', fontproperties=my_font)
plt.grid(True, linestyle=':')
plt.show()
这种方法最大的优势是免安装、免重启、免改系统配置。只需将字体文件打包随代码一同分发,就能保证在任何机器上直接运行且效果完全一致。
五、常见问题排查与注意事项
1. 如何准确查询当前环境已安装的中文字体名称?
有时代码中指定了 SimHei 或 Microsoft YaHei 依然报错,往往是因为字体的实际内部名称(Family Name)与字体的显示名称不同。可以通过 fontManager 遍历打印当前系统注册的所有中文字体实际名称:
import matplotlib.font_manager as fm
# 查找所有支持中文字符集或者包含中文关键词的字体名称
cjk_fonts = set()
for f in fm.fontManager.ttflist:
# 筛选常见的中文字体名
name = f.name
if any(k in name.lower() for k in ['hei', 'song', 'kai', 'fang', 'cjk', 'pingfang', 'yahei', 'unicode']):
cjk_fonts.add(name)
print("当前系统已识别的中文兼容字体:")
for font in sorted(cjk_fonts):
print("-", font)
2. Linux / Docker 容器环境缺少字库
在 Linux 服务器或精简版 Docker 容器中,系统往往默认未安装任何 CJK 字体包。此时即使配置了 sans-serif 依然无效。在 Ubuntu/Debian 系统中可直接通过包管理器补齐文泉驿开源字库:
# 在终端执行安装命令
sudo apt-get update
sudo apt-get install -y fonts-wqy-microhei fonts-wqy-zenhei
# 刷新操作系统字体缓存
fc-cache -fv
安装完成后,在 Python 中将字体配置为 'WenQuanYi Micro Hei' 即可正常出图。
3. Jupyter Notebook 配置未生效
在 Jupyter Notebook 中修改了 rcParams 或安装了新字体后,由于当前的 Python Kernel 依然驻留了旧的字体缓存对象,必须点击菜单栏的 Kernel -> Restart 重启内核,修改才会真正生效。
六、总结与配置建议
解决 Matplotlib 中文乱码的核心逻辑非常纯粹:提供可用中文字体 + 关停负号 Unicode 转换。在实际项目开发中,建议采用以下分级策略:
- 临时探索与脚本分析:直接在代码首部使用跨平台
plt.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'SimHei', 'sans-serif']和plt.rcParams['axes.unicode_minus'] = False,具有最高的敏捷度与通用性。 - 生产环境自动化出图:如果是在统一的服务器或容器中跑报表任务,建议将文泉驿等开源字体打包进 Docker 镜像,并在
matplotlibrc中固化配置,使业务代码保持纯粹无侵入。 - 特殊排版需求:利用
FontProperties(fname=...)进行局部微调,精确控制图例、副标题等不同组件的字重与字体风格。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









