解决Python画图中文乱码:matplotlib字体配置方法

南乔
南乔
发布时间:2026-11-22| 3人浏览过
原创

全面解析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),进而再次引发字形缺失。

解决Python画图中文乱码:matplotlib字体配置方法
图1:Matplotlib 文本渲染流程与字形查找机制对比

二、方法一:脚本级动态配置(推荐常规使用)

动态配置是日常数据探索与单脚本开发中最常用的方式。通过在导入 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 并配合安装字体文件,实现系统级默认支持中文。

解决Python画图中文乱码:matplotlib字体配置方法
图2:全局持久化配置与字体缓存刷新工作流

详细操作说明

  1. 获取配置与字体目录: 在终端或交互环境中运行以下代码:
    import matplotlib
    print("字体存放目录:", matplotlib.get_data_path() + '/fonts/ttf')
    print("缓存目录:", matplotlib.get_cachedir())
    print("用户配置文件路径:", matplotlib.matplotlib_fname())
  2. 放入字体文件: 下载或从系统字体库(如 Windows 的 C:\Windows\Fonts\simhei.ttf)中拷贝字体至上述的 fonts/ttf 文件夹下。
  3. 修改 matplotlibrc 文件: 使用文本编辑器打开 matplotlib.matplotlib_fname() 所指向的文件,找到并去除以下三项前面的 # 注释,修改为:
    font.family         : sans-serif
    font.sans-serif      : SimHei, DejaVu Sans
    axes.unicode_minus   : False
  4. 删除旧缓存文件: 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()

这种方法最大的优势是免安装、免重启、免改系统配置。只需将字体文件打包随代码一同分发,就能保证在任何机器上直接运行且效果完全一致。

解决Python画图中文乱码:matplotlib字体配置方法
图3:Matplotlib 三种中文配置策略对比与技术权衡

五、常见问题排查与注意事项

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 重启内核,修改才会真正生效。

解决Python画图中文乱码:matplotlib字体配置方法
图4:Matplotlib 中文乱码排查决策与解决方案总结

六、总结与配置建议

解决 Matplotlib 中文乱码的核心逻辑非常纯粹:提供可用中文字体 + 关停负号 Unicode 转换。在实际项目开发中,建议采用以下分级策略:

  • 临时探索与脚本分析:直接在代码首部使用跨平台 plt.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'SimHei', 'sans-serif'] 和 plt.rcParams['axes.unicode_minus'] = False,具有最高的敏捷度与通用性。
  • 生产环境自动化出图:如果是在统一的服务器或容器中跑报表任务,建议将文泉驿等开源字体打包进 Docker 镜像,并在 matplotlibrc 中固化配置,使业务代码保持纯粹无侵入。
  • 特殊排版需求:利用 FontProperties(fname=...) 进行局部微调,精确控制图例、副标题等不同组件的字重与字体风格。
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。