Python Matplotlib绘图中文显示方框怎么解决

拾柒

发布时间：2026-10-30 | 6人浏览过

原创

针对Python使用Matplotlib绘图时中文标题、坐标轴标签显示为方框（豆腐块）的问题，本文详细解析其产生机理，并提供全局rcParams配置、局部FontProperties指定、负号显示修复以及缓存清理等完整的解决方案与多平台字体参考。

在Python中使用Matplotlib库绘制图表时，如果标题、坐标轴标签或图例包含中文字符，渲染出来的文字常会变成空心小方框（常被称为豆腐块 Tofu）。解决这一问题的核心在于明确指定支持中文的字体，并通过配置关闭Unicode负号的自动转换。本文将详细解释问题根源，并给出全局配置与局部指定的具体操作步骤及常见排查方法。

一、中文显示为方框的根本原因

Matplotlib在默认安装状态下，内置使用的西文字体是DejaVu Sans。这种字体只包含了ASCII和部分拉丁字符集，字库中并没有收录中文字形。当Matplotlib尝试将包含汉字的字符串渲染到画布上时，在指定的字库中找不到对应的字形编码（Glyph），排版引擎便会退回到缺失字形表示，即绘制为一个空白的矩形框。

此外，许多操作系统自带了中文字体，但Matplotlib为了保证绘图脚本跨平台运行的基准一致性，默认并不会主动去探测并选用系统的本地化中文字体，因此需要开发者在脚本中显式指明使用哪一种中文字体。

图1：Matplotlib默认字形缺失与配置中文字体后的渲染流程分析

二、解决方法一：全局配置 rcParams（推荐做法）

这是日常数据分析与可视化中最推荐的方式。只需在导入Matplotlib模块后，在脚本头部设置两条参数，即可对整个脚本或当前Jupyter Notebook单元格的所有绘图操作全局生效。

1. 关键代码示例

在创建任何图表（调用 plt.figure() 或 plt.plot()）之前加入以下两行配置：

import matplotlib.pyplot as plt

# 1. 设置无衬线字体优先级，首选中文字体（如黑体 SimHei）
plt.rcParams['font.sans-serif'] = ['SimHei', 'DejaVu Sans']

# 2. 正常显示负号（解决负号变成方框的问题）
plt.rcParams['axes.unicode_minus'] = False

# 示例绘图
x = ['一月', '二月', '三月', '四月']
y = [-12, 5, 18, 24]

plt.figure(figsize=(6, 3.5))
plt.plot(x, y, marker='o')
plt.title('季度平均气温走势')
plt.xlabel('月份')
plt.ylabel('气温 (°C)')
plt.grid(True, linestyle='--', alpha=0.6)
plt.show()

2. 为什么必须设置 axes.unicode_minus = False

很多初学者在设置了 font.sans-serif 之后，发现中文能够正常显示了，但是坐标轴上的负数负号（如 -10、-20）却又变成了方框。这是因为Matplotlib为了排版美观，默认会使用Unicode标准减号符号（ASCII 8722 / U+2212 '−'），而不是常规键盘上的连字符减号（ASCII 45 / U+002D '-'）。不少中文字体库（如SimHei）并没有对Unicode字符U+2212进行对应设计。将 axes.unicode_minus 设为 False 后，Matplotlib就会改用标准的ASCII减号渲染负数，从而彻底消除负号方框。

图2：解决Matplotlib中文方框的标准化四步排查流程

三、解决方法二：局部指定 FontProperties（精细控制）

在某些场景下，我们可能不希望修改整个项目的全局配置，或者需要在同一幅图表中同时展示不同字体（例如标题使用黑体，数据标签使用楷体），或者代码需要分发给他人运行、而对方操作系统并没有安装指定的中文字体。此时，使用 matplotlib.font_manager.FontProperties 进行局部控制是最理想的手段。

1. 直接通过系统字体名局部指定

可以通过传入系统已经安装的字体名称来构建字体属性对象：

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

# 创建字体属性对象（指定系统字体名称，如微软雅黑）
font_title = FontProperties(family='Microsoft YaHei', size=14, weight='bold')
font_label = FontProperties(family='Microsoft YaHei', size=11)

plt.figure(figsize=(6, 3.5))
plt.plot([1, 2, 3], [10, 20, 15])

# 在具体的文本输出函数中显式传入 fontproperties 参数
plt.title('各季度营收分析', fontproperties=font_title)
plt.xlabel('季度阶段', fontproperties=font_label)
plt.ylabel('金额 (万元)', fontproperties=font_label)

plt.show()

2. 直接加载本地字体文件（.ttf / .otf）

如果是在无管理员权限的Linux服务器或云函数容器中运行代码，或者希望项目打包后在任何机器上都能开箱即用，可以直接将开源中文字体文件（如思源黑体 SourceHanSansCN-Regular.otf）存放在项目目录中，使用 fname 参数直接加载：

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

# 指向本地字体文件的绝对路径或相对路径
my_font = FontProperties(fname='./fonts/SourceHanSansCN-Regular.otf', size=12)

plt.figure()
plt.plot([1, 2], [3, 4])
plt.title('完全独立于系统的中文标题', fontproperties=my_font)
plt.show()

四、全局配置与局部指定的关键差异对比

在实际开发中，全局配置和局部指定各自有清晰的适用边界。了解两者的差异有助于在工程实践中做出最合理的架构设计。

图3：两种核心解决方案的关键特性与选型对比

五、主流操作系统常用中文字体名称速查

在配置 plt.rcParams['font.sans-serif'] 时，必须确保所填写的字体名称在当前操作系统中真实存在。若填入了宿主机没有安装的字体，Matplotlib会在警告后退回到默认西文字体，依然会导致方框。以下是主流平台的内置中文可用字体名称：

操作系统	推荐首选字体名	备选中文字体名	说明
Windows	`SimHei` (黑体)	`Microsoft YaHei` (微软雅黑), `SimSun` (宋体)	Windows默认预装，直接填英文字体名即可生效。
macOS	`PingFang SC` (苹方-简)	`Arial Unicode MS`, `Heiti TC`	macOS通常没有SimHei，填SimHei无效，建议填PingFang SC。
Linux (Ubuntu/CentOS)	`Noto Sans CJK SC`	`WenQuanYi Micro Hei` (文泉驿微米黑)	很多精简Linux镜像不带中文字体，需通过apt/yum安装。

跨平台兼容写法提示： 由于 font.sans-serif 接收的是一个列表，Matplotlib会按从左到右的顺序逐一尝试。因此可以编写跨平台通用的字体回退列表：
plt.rcParams['font.sans-serif'] = ['SimHei', 'PingFang SC', 'Microsoft YaHei', 'WenQuanYi Micro Hei', 'sans-serif']
这样无论脚本在Windows、macOS还是Linux上运行，都能自动命中当前系统存在的可用中文字体。

六、设置了字体仍然显示方框？常见原因与解决办法

1. 字体缓存未刷新（最常见顽疾）

Matplotlib首次运行时会扫描系统字体，并在用户主目录下生成一个缓存文件（例如 fontlist-v330.json）。如果你是在安装了中文字体之后再运行Matplotlib，或者更新了环境，Matplotlib可能依然读取的是旧缓存，导致它找不到新字体。

解决方法：在Python中查看并删除缓存目录：

import matplotlib
# 查看缓存路径
print(matplotlib.get_cachedir())

找到输出的路径（例如 ~/.cache/matplotlib 或 C:\Users\用户名\.matplotlib），将里面的 fontlist-*.json 缓存文件直接删除，然后完全重启Python脚本或重启Jupyter Notebook内核，Matplotlib会自动重新构建字体索引。

2. 字体名称大小写或拼写错误

字体名称对空格和大小写非常敏感。例如 'PingFang SC' 不能拼成 'pingfang'，'SimHei' 不能写成 'simhei'。如需查询当前机器已被Matplotlib识别的所有中文字体名称，可以运行以下代码：

from matplotlib.font_manager import fontManager

# 打印所有支持中文特征的字体名称
chinese_fonts = [f.name for f in fontManager.ttflist if any(k in f.name for k in ['Hei', 'Song', 'Kai', 'Ming', 'Fang', 'YaHei'])]
print(set(chinese_fonts))

3. Linux服务器缺失中文字体包

在基于Docker、Ubuntu Server等无GUI环境的Linux系统中，系统往往是纯英文最小化镜像，此时需要主动安装字体包：

# Ubuntu / Debian
sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei

# CentOS / RHEL
sudo yum install -y google-noto-sans-cjk-fonts

安装完成后，删除前述提到的Matplotlib缓存并重启服务即可。

图4：Matplotlib中文显示最终排查与配置自检指南

七、总结

解决Matplotlib绘图中文显示方框的核心结论可以归纳为三点：

配置中文字体族：通过 plt.rcParams['font.sans-serif'] 指定系统内置的中文字体（如Windows首选SimHei，macOS首选PingFang SC）。
关闭Unicode负号：务必设置 plt.rcParams['axes.unicode_minus'] = False，防止坐标轴上的负号因编码不支持再度退化为方框。
善用缓存重置与独立字体：配置无效时优先清理 fontlist-*.json 缓存文件；若需要严格的跨系统一致性，采用 FontProperties 携带 .ttf/.otf 字体文件是最佳工程实践。