Python报错FontNotFoundError或字体显示方框怎么排查

木白
木白
发布时间:2026-11-20| 3人浏览过
原创

深入解析Python中Matplotlib及Pillow绘图时出现FontNotFoundError报错或中文字体显示为方框(豆腐块)的原因,提供系统排查步骤、对比方案及跨平台配置指南。

在 Python 中使用 Matplotlib、Seaborn 或 Pillow 进行数据可视化与图像绘制时,中文乱码和字体缺失是极为高频的异常。解决这个问题的核心逻辑只有两步:先区分异常属于“字体文件完全未找到”还是“字体文件中缺少中文对应字形(Glyph)”,再根据运行环境选择修改全局配置或直接加载字体文件路径。

一、明确异常表现:两类本质不同的故障

虽然开发者通常都把问题统称为“中文出不来”,但实际上它们在底层是两组完全不同的错误机制,排查路径也各不相同:

  • 表现一:中文显示为空白方框(豆腐块 / Tofu)并伴随警告
    终端通常输出 UserWarning: Glyph 20013 (\N{CJK UNIFIED IDEOGRAPH-4E2D}) missing from font(s) DejaVu Sans。这表明 Python 成功找到了字体文件并正常完成了绘图,但当前所使用的字体文件(如默认的 DejaVu Sans、Bitstream Vera Sans)只包含拉丁字母与西文字符,根本没有收入汉字编码区,渲染引擎找不到字形,只能绘制默认的缺字替代符(方框)。
  • 表现二:直接抛出致命异常 FontNotFoundError 或 OSError: cannot open resource
    这通常发生在 Pillow (ImageFont.truetype())、ReportLab 或在代码中显式指定不存在的字体路径时。这表明操作系统或代码在给定的路径下物理上找不到该字体文件,程序会直接中断执行。
Python报错FontNotFoundError或字体显示方框怎么排查
图 1:Python 绘图字体报错的分类与核心判断流

二、解决方案对比:系统字体名称配置 vs 字体文件路径加载

针对字体配置,社区中主要存在两种实现思路:一种是通过 rcParams['font.sans-serif'] 指定系统字体家族名;另一种是通过 FontProperties(fname=...) 直接显式指定字体文件。在不同生产环境下,两者的差异至关重要。

对比维度 方式一:配置系统字体名称 (rcParams) 方式二:直接引用字体文件路径 (FontProperties)
核心原理 告诉渲染器字体族名(如 SimHei),由 Matplotlib 在系统已缓存的字体索引中搜索匹配 直接打开指定的 .ttf 或 .otf 二进制文件解析,跳过系统字体索引库
代码侵入度 极低,只需在脚本开头设置一次,所有绘图自动生效 较高,每个含有中文的标签或标题都需要传递 fontproperties 参数
环境依赖性 强依赖宿主机系统。不同系统字体名不一致(Windows是黑体,macOS是苹方) 完全摆脱宿主机系统字体限制,只要字体文件随工程打包即可运行
缓存问题 容易受到 fontlist-*.json 缓存滞后干扰,新装字体可能不识别 不受缓存影响,即载即用
推荐场景 个人本地开发、Jupyter 数据交互式探索 团队协作、CI/CD 自动化流水线、Docker 容器部署、服务器定时脚本
Python报错FontNotFoundError或字体显示方框怎么排查
图 2:系统字体解析与文件绝对路径加载的机制对比

三、Matplotlib 中文方框排查与修复步骤

如果你在 Matplotlib 中遇到中文显示为方框,请按照以下标准四步流程进行排查与修复:

第一步:确认当前系统中已有的中文字体

在 Python 中直接查询 Matplotlib 能够识别的字体列表,不要凭空猜测字体名称。在终端或交互式环境中运行以下检查脚本:

import matplotlib.font_manager as fm

# 遍历系统字体库,筛选出常见中文字体名称
cjk_keywords = ['hei', 'song', 'kai', 'ming', 'yuan', 'pingfang', 'yahei', 'cjk']
found_fonts = []

for f in fm.fontManager.ttflist:
    name_lower = f.name.lower()
    if any(keyword in name_lower for keyword in cjk_keywords):
        found_fonts.append((f.name, f.fname))

# 去重输出
unique_fonts = sorted(list(set(found_fonts)))
for name, path in unique_fonts:
    print(f"字体名称: {name}  -->  物理路径: {path}")

示例输出:

字体名称: Microsoft YaHei  -->  物理路径: C:\Windows\Fonts\msyh.ttc
字体名称: PingFang SC     -->  物理路径: /System/Library/Fonts/PingFang.ttc
字体名称: SimHei          -->  物理路径: C:\Windows\Fonts\simhei.ttf

如果输出为空,说明当前系统环境中根本未安装中文字体(在 Linux Docker 最小化镜像中尤其常见),必须先安装字体文件。

第二步:清理 Matplotlib 字体缓存

Matplotlib 会把扫描到的系统字体缓存在用户目录的一个 JSON 文件中。如果你刚安装了新字体,或者反复修改了配置却依旧无效,必须删除该缓存文件让其重新扫描:

import matplotlib
import os
import shutil

cache_dir = matplotlib.get_cachedir()
print("当前缓存目录为:", cache_dir)

# 寻找形如 fontlist-vXXX.json 的文件并删除
for file_name in os.listdir(cache_dir):
    if file_name.startswith("fontlist-") and file_name.endswith(".json"):
        target_file = os.path.join(cache_dir, file_name)
        os.remove(target_file)
        print(f"已清理字体缓存: {target_file}")

第三步:在绘图代码中显式配置字体与负号

在脚本入口处添加跨平台字体优先级列表,并务必关闭负号 Unicode 转换:

import matplotlib.pyplot as plt

# 1. 设置无衬线字体优先级列表,适配 Windows、macOS 与 Linux
plt.rcParams['font.sans-serif'] = [
    'PingFang SC',       # macOS 苹方
    'Microsoft YaHei',   # Windows 微软雅黑
    'SimHei',            # Windows 黑体
    'Noto Sans CJK SC',  # Linux / Google Noto 简体中文
    'WenQuanYi Micro Hei',# Linux 文泉驿微米黑
    'sans-serif'         # 回退备选
]

# 2. 核心避坑:解决负号 '-' 显示为方块的问题
plt.rcParams['axes.unicode_minus'] = False
为什么负号也会变成方框?
默认情况下,Matplotlib 会使用 Unicode 减号字符 U+2212(MINUS SIGN)来绘制坐标轴负数。然而绝大部分中文字体并未实现该字符,导致坐标轴负数变成了方框。设置 axes.unicode_minus = False 会让坐标轴强制回退到标准 ASCII 减号 U+002D(HYPHEN-MINUS),从而正常显示。
Python报错FontNotFoundError或字体显示方框怎么排查
图 3:Matplotlib 中文排查与修复四步流

第四步:运行验证脚本

使用以下包含了负数、中文标题与中文图例的最小化验证代码:

import matplotlib.pyplot as plt

plt.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'SimHei', 'sans-serif']
plt.rcParams['axes.unicode_minus'] = False

fig, ax = plt.subplots(figsize=(6, 3))
ax.plot([-3, -1, 2, 4], [10, -5, 15, -8], label="温度趋势曲线")
ax.set_title("测试中文标题与负号显示")
ax.set_xlabel("横轴偏差 (包含负数 -3, -1)")
ax.set_ylabel("数值 (包含负数 -5, -8)")
ax.legend()

plt.tight_layout()
plt.savefig("font_test.png", dpi=150)
print("验证图片生成完成:font_test.png")

四、Pillow / ReportLab 中的 FontNotFoundError 排查

如果是在 Pillow 或 ReportLab 中遇到了致命的 FontNotFoundError 或 OSError: cannot open resource,核心排查思路是检查文件路径与格式支持:

from PIL import Image, ImageDraw, ImageFont
import os

font_path = "simhei.ttf"

# 排查关键:验证文件是否存在于物理磁盘
if not os.path.exists(font_path):
    print(f"错误:字体文件 {font_path} 不存在!请使用绝对路径或将字体放至当前工作目录。")
else:
    try:
        font = ImageFont.truetype(font_path, size=24)
        image = Image.new("RGB", (300, 100), color=(255, 255, 255))
        draw = ImageDraw.Draw(image)
        draw.text((20, 35), "中文绘制正常", font=font, fill=(0, 0, 0))
        image.save("pillow_test.png")
        print("Pillow 中文字体加载成功!")
    except OSError as e:
        print("字体文件损坏或格式不受支持:", e)

五、常见特殊环境与注意事项

Python报错FontNotFoundError或字体显示方框怎么排查
图 4:环境特殊场景与生产部署自检清单
  • Linux 服务器与 Docker 容器缺字:最彻底的做法是直接随工程分发一款开源中文字体(如思源黑体 SourceHanSansSC-Regular.otf 或 NotoSansSC-Regular.otf),并通过相对路径引用,无需在宿主机安装任何系统包。
  • Jupyter 笔记本环境:修改 Matplotlib 配置或删除缓存后,必须执行 Kernel → Restart Kernel,因为 Matplotlib 的字体索引在模块首次 import 时已被载入内存,仅重跑单元格无法重新初始化缓存。
  • 字体名称不要带文件名后缀:在 rcParams['font.sans-serif'] 中传入的是字体家族名(Family Name,如 'SimHei'、'Microsoft YaHei'),而不是磁盘文件名(不要写成 'simhei.ttf')。

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

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 算法库。