问题背景Matplotlib 默认字体不包含中文字形在图表标题、坐标轴标签中使用中文时会出现方块或警告。常见做法是修改全局rcParams但这依赖系统已安装对应字体换台机器就可能失效。本文介绍一种更可控的方式将字体文件放在项目目录内通过font_manager.fontManager.addfont在当前进程中注册无需修改系统字体。环境与前置条件项目版本/说明Python3.10.13Matplotlib3.10.8字体LXGW WenKai Lite TTF Version 1.530实测系统macOS 27.0.1 arm64Windows 和 Linux 用户可参照相同目录结构本文未在这两个系统上实测。下面的 python 应指向你实际使用的解释器使用虚拟环境时先激活对应环境。安装本次示例的依赖python-mpipinstallmatplotlib3.10.8字体获取与项目目录霞鹜文楷轻便版是开源中文字体适合正文排版与图表标注。请从作者项目仓库的fonts/TTF/目录下载LXGWWenKaiLite-Regular.ttf约 13.3 MiBVersion 1.530。下载字体文件不等于安装系统字体本文仅将其作为项目资源使用。从作者 TTF 目录取得字体同时保留仓库的 OFL.txt。整理字体资料时一起记录来源、版本、实际文件路径与许可文件方便项目迁移后复核。将字体放入与脚本同级的fonts目录project/ ├── demo.py └── fonts/ └── LXGWWenKaiLite-Regular.ttf完整可运行示例以下为demo.py完整代码可直接运行frompathlibimportPathimportmatplotlib matplotlib.use(Agg)# 命令行导出图片不依赖桌面显示器importmatplotlib.pyplotaspltfrommatplotlibimportfont_manager basePath(__file__).resolve().parent font_pathbase/fonts/LXGWWenKaiLite-Regular.ttfifnotfont_path.is_file():raiseFileNotFoundError(f请把字体文件放到{font_path})font_manager.fontManager.addfont(str(font_path))familyfont_manager.FontProperties(fnamestr(font_path)).get_name()withplt.rc_context({font.family:family,axes.unicode_minus:True}):fig,axplt.subplots(figsize(8,4.5),layoutconstrained)ax.plot([1,2,3],[-2,1,3],markero,color#2f60c8)ax.set_title(项目内字体中文图表验证,fontsize18)ax.set_xlabel(月份)ax.set_ylabel(变化值示例数据)ax.set_xticks([1,2,3],[一月,二月,三月])ax.axhline(0,color#aab3c4,linewidth0.8)ax.grid(alpha0.2)outputbase/中文图表.pngfig.savefig(output,dpi160)plt.close(fig)print(Matplotlib:,matplotlib.__version__)print(Font family:,family)print(Font file:,font_manager.findfont(family,fallback_to_defaultFalse))print(Output:,output)Jupyter 环境注意Path(__file__)在 Jupyter Notebook 中不可用可改用Path.cwd()并确认当前工作目录包含fonts/子目录basePath.cwd()font_pathbase/fonts/LXGWWenKaiLite-Regular.ttf运行与结果cdproject python demo.py本次实际运行打印 Matplotlib 3.10.8、Font family: LXGW WenKai LiteFont file 指向项目内的字体文件Output 指向脚本目录下的中文图表.png。示例使用 Agg 后端直接保存文件不会弹出窗口。findfont(family, fallback_to_defaultFalse) 用于检查实际匹配路径同一进程内有其他同名字体版本时也请核对路径是否符合预期。生成的中文图表.png1280×720 像素中标题、坐标轴标签均为中文正常显示负数-2的负号也正确渲染无 Glyph 缺字警告。折线数据只用于显示验证不代表业务指标。常见问题addfont 是否永久生效不是。addfont仅对当前 Python 进程有效每次新启动解释器或重启内核后需重新执行注册代码。为什么用 rc_context 而不是直接改 rcParamsrc_context是上下文管理器退出后恢复原设置避免污染后续绘图的全局配置。出现 Glyph missing 警告怎么办说明所用字体缺少对应字形。霞鹜文楷轻便版为 Lite 子集生僻字可能未覆盖需另选完整字库或换用其他字体。Windows/Linux 路径有区别吗pathlib.Path本身跨平台只要目录结构一致代码无需修改。但本文仅在 macOS 上实测其他系统如遇问题请检查文件路径和权限。字体适用边界与许可提示霞鹜文楷轻便版采用 SIL OFL 1.1 许可再分发时须附带OFL.txt不得单独售卖字体文件。Lite 版本字库为常用字子集若图表涉及生僻字或繁体扩展区请核对字形覆盖或选用完整版。本文演示字体取自作者仓库fonts/TTF/LXGWWenKaiLite-Regular.ttfVersion 1.530其他渠道获取的同名字体版本可能不同建议以文件内嵌版本号为准。配套字体资料我整理的霞鹜文楷轻便版字体资料也提供夸克网盘分享方便需要集中保存字体文件的读者打开配套字体资料夸克网盘分享目录当前为 1 个 ZIP约 48.3 MiB。打开后可查看文件清单保存或下载可能需要登录夸克请以网盘实际提示为准。压缩包内的字体版本以实际文件为准上文 Version 1.530 的运行示例使用作者仓库中的 TTF。请同时保留并遵守字体的 OFL 许可文件也可继续使用上文的作者仓库入口获取字体。官方参考霞鹜文楷轻便版作者项目作者项目 OFL.txtMatplotlib 字体管理 API本文由 AI 辅助起草示例代码经实际运行并人工核对。 
长河君 · 2026/10/18 13:45:44 · 阅读 1.2k Matplotlib中文乱码：用项目内字体文件生成中文图表
问题背景Matplotlib 默认字体不包含中文字形在图表标题、坐标轴标签中使用中文时会出现方块或警告。常见做法是修改全局rcParams但这依赖系统已安装对应字体换台机器就可能失效。本文介绍一种更可控的方式将字体文件放在项目目录内通过font_manager.fontManager.addfont在当前进程中注册无需修改系统字体。环境与前置条件项目版本/说明Python3.10.13Matplotlib3.10.8字体LXGW WenKai Lite TTF Version 1.530实测系统macOS 27.0.1 arm64Windows 和 Linux 用户可参照相同目录结构本文未在这两个系统上实测。下面的 python 应指向你实际使用的解释器使用虚拟环境时先激活对应环境。安装本次示例的依赖python-mpipinstallmatplotlib3.10.8字体获取与项目目录霞鹜文楷轻便版是开源中文字体适合正文排版与图表标注。请从作者项目仓库的fonts/TTF/目录下载LXGWWenKaiLite-Regular.ttf约 13.3 MiBVersion 1.530。下载字体文件不等于安装系统字体本文仅将其作为项目资源使用。从作者 TTF 目录取得字体同时保留仓库的 OFL.txt。整理字体资料时一起记录来源、版本、实际文件路径与许可文件方便项目迁移后复核。将字体放入与脚本同级的fonts目录project/ ├── demo.py └── fonts/ └── LXGWWenKaiLite-Regular.ttf完整可运行示例以下为demo.py完整代码可直接运行frompathlibimportPathimportmatplotlib matplotlib.use(Agg)# 命令行导出图片不依赖桌面显示器importmatplotlib.pyplotaspltfrommatplotlibimportfont_manager basePath(__file__).resolve().parent font_pathbase/fonts/LXGWWenKaiLite-Regular.ttfifnotfont_path.is_file():raiseFileNotFoundError(f请把字体文件放到{font_path})font_manager.fontManager.addfont(str(font_path))familyfont_manager.FontProperties(fnamestr(font_path)).get_name()withplt.rc_context({font.family:family,axes.unicode_minus:True}):fig,axplt.subplots(figsize(8,4.5),layoutconstrained)ax.plot([1,2,3],[-2,1,3],markero,color#2f60c8)ax.set_title(项目内字体中文图表验证,fontsize18)ax.set_xlabel(月份)ax.set_ylabel(变化值示例数据)ax.set_xticks([1,2,3],[一月,二月,三月])ax.axhline(0,color#aab3c4,linewidth0.8)ax.grid(alpha0.2)outputbase/中文图表.pngfig.savefig(output,dpi160)plt.close(fig)print(Matplotlib:,matplotlib.__version__)print(Font family:,family)print(Font file:,font_manager.findfont(family,fallback_to_defaultFalse))print(Output:,output)Jupyter 环境注意Path(__file__)在 Jupyter Notebook 中不可用可改用Path.cwd()并确认当前工作目录包含fonts/子目录basePath.cwd()font_pathbase/fonts/LXGWWenKaiLite-Regular.ttf运行与结果cdproject python demo.py本次实际运行打印 Matplotlib 3.10.8、Font family: LXGW WenKai LiteFont file 指向项目内的字体文件Output 指向脚本目录下的中文图表.png。示例使用 Agg 后端直接保存文件不会弹出窗口。findfont(family, fallback_to_defaultFalse) 用于检查实际匹配路径同一进程内有其他同名字体版本时也请核对路径是否符合预期。生成的中文图表.png1280×720 像素中标题、坐标轴标签均为中文正常显示负数-2的负号也正确渲染无 Glyph 缺字警告。折线数据只用于显示验证不代表业务指标。常见问题addfont 是否永久生效不是。addfont仅对当前 Python 进程有效每次新启动解释器或重启内核后需重新执行注册代码。为什么用 rc_context 而不是直接改 rcParamsrc_context是上下文管理器退出后恢复原设置避免污染后续绘图的全局配置。出现 Glyph missing 警告怎么办说明所用字体缺少对应字形。霞鹜文楷轻便版为 Lite 子集生僻字可能未覆盖需另选完整字库或换用其他字体。Windows/Linux 路径有区别吗pathlib.Path本身跨平台只要目录结构一致代码无需修改。但本文仅在 macOS 上实测其他系统如遇问题请检查文件路径和权限。字体适用边界与许可提示霞鹜文楷轻便版采用 SIL OFL 1.1 许可再分发时须附带OFL.txt不得单独售卖字体文件。Lite 版本字库为常用字子集若图表涉及生僻字或繁体扩展区请核对字形覆盖或选用完整版。本文演示字体取自作者仓库fonts/TTF/LXGWWenKaiLite-Regular.ttfVersion 1.530其他渠道获取的同名字体版本可能不同建议以文件内嵌版本号为准。配套字体资料我整理的霞鹜文楷轻便版字体资料也提供夸克网盘分享方便需要集中保存字体文件的读者打开配套字体资料夸克网盘分享目录当前为 1 个 ZIP约 48.3 MiB。打开后可查看文件清单保存或下载可能需要登录夸克请以网盘实际提示为准。压缩包内的字体版本以实际文件为准上文 Version 1.530 的运行示例使用作者仓库中的 TTF。请同时保留并遵守字体的 OFL 许可文件也可继续使用上文的作者仓库入口获取字体。官方参考霞鹜文楷轻便版作者项目作者项目 OFL.txtMatplotlib 字体管理 API本文由 AI 辅助起草示例代码经实际运行并人工核对。