Python Matplotlib Chinese Font

v1.0.0

Configure matplotlib to display Chinese by adding a Chinese font file with font_manager.addfont(), setting rcParams['font.family'], and disabling unicode_minus.

⭐ 0· 7·0 current·0 all-time

by@earl-chen

MIT-0

Security Scan

VirusTotal

Benign

View report →

OpenClaw

Benign

high confidence

✓

Purpose & Capability

Name/description match the included templates and helper modules: all code focuses on loading a local TTF and setting matplotlib rcParams. There are no unrelated dependencies or credentials requested.

✓

Instruction Scope

SKILL.md and templates only instruct downloading a font (explicit curl/wget to a public font URL), copying a template, adding the font to matplotlib, and running local tests. The instructions reference local file paths and the project's fonts directory; they do not read unrelated system files or send data to external endpoints beyond the font download.

✓

Install Mechanism

No install spec; the skill is instruction-plus-template-only. Code files are benign Python helpers and tests. The only external network action suggested is downloading a font from a public project site, which is reasonable for this purpose.

✓

Credentials

The skill requires no environment variables, credentials, or config paths. It only accesses local filesystem paths for fonts and writes a test PNG to the working directory — proportional to the stated purpose.

✓

Persistence & Privilege

always is false, the skill doesn't request persistent elevated privileges, and it doesn't modify other skills or global agent configuration. It only registers fonts with matplotlib's font manager at runtime.

Assessment

This skill appears coherent and limited to enabling Chinese fonts in matplotlib. Before using: (1) verify and accept the font's license (BabelStoneHan is large ~50MB); (2) download the font from a trusted source and inspect it before adding to your project; (3) note the test script will save test_chinese_font.png to your current working directory; and (4) when copying the template, update the _FONT_FILE_RELATIVE path to point to your actual fonts/ location. If you prefer not to download a new font, you can instead point the templates to a system-installed Chinese font (e.g., SimHei or Microsoft YaHei) if available.

Like a lobster shell, security has layers — review code before you run it.

latestvk97eannefg883gx1qh472z55y9842pzk

License

MIT-0

Free to use, modify, and redistribute. No attribution required.

Termshttps://spdx.org/licenses/MIT-0.html

SKILL.md

python-matplotlib-chinese-font

Python matplotlib 中文字体配置解决方案

📌 问题描述

matplotlib 默认不支持中文，中文会显示为方块/方框

控制台警告：

UserWarning: Glyph XXXXX missing from current font

根本原因：matplotlib 的默认字体不包含中文字符。

🎯 使用场景

当以下情况时使用此 Skill：

✅ matplotlib 绑图中中文显示为方框/乱码
✅ 需要配置中文字体
✅ 负号显示为方框
✅ 图例、标题、坐标轴标签中文显示异常
✅ 跨平台字体兼容问题
✅ 字体路径配置问题
✅ 字体缓存问题

🚀 快速开始

第 0 步：下载字体文件

# 创建字体目录
mkdir -p fonts

# 下载 BabelStoneHan 字体（约 50MB）
curl -L -o fonts/BabelStoneHan.ttf "https://www.babelstone.co.uk/Fonts/Download/BabelStoneHan.ttf"

# 或者使用 wget
wget -O fonts/BabelStoneHan.ttf "https://www.babelstone.co.uk/Fonts/Download/BabelStoneHan.ttf"

其他字体选择（小于 10MB）：

WenQuanYi Micro Hei (文泉驿微米黑) - 约 4MB
SimHei (黑体) - 系统自带
Microsoft YaHei (微软雅黑) - Windows 系统自带

方法 1：复制模板（推荐）

# 复制配置模板到你的项目
cp ~/.openclaw/skills/python-matplotlib-chinese-font/templates/setup_font.py ./

方法 2：直接使用字体文件

import os
import matplotlib.pyplot as plt
from matplotlib import font_manager as fm

# 字体文件路径（请修改为你的实际路径）
font_file = './fonts/BabelStoneHan.ttf'

# 关键：显式添加字体
fm.fontManager.addfont(font_file)

# 创建 FontProperties
font_prop = fm.FontProperties(fname=font_file)

# 设置全局字体
plt.rcParams['font.family'] = font_prop.get_name()
plt.rcParams['axes.unicode_minus'] = False

# 使用
fig, ax = plt.subplots()
ax.set_title('中文标题', fontproperties=font_prop)
ax.set_xlabel('横轴', fontproperties=font_prop)
ax.legend(['图例'], prop=font_prop)

📋 完整配置代码（3 步）

第 1 步：下载并准备字体文件

# 创建字体目录
mkdir -p fonts

# 下载 BabelStoneHan 字体
curl -L -o fonts/BabelStoneHan.ttf "https://www.babelstone.co.uk/Fonts/Download/BabelStoneHan.ttf"

项目结构：

your_project/
├── fonts/
│   └── BabelStoneHan.ttf  ← 中文字体文件（需自行下载）
├── scripts/
│   └── your_script.py
└── ...

字体推荐：

BabelStoneHan.ttf（开源，支持中文）← 需自行下载，约 50MB
SimHei.ttf（黑体）- 系统自带
Microsoft YaHei.ttf（微软雅黑）- Windows 系统自带
WenQuanYi Micro Hei（文泉驿微米黑）- 约 4MB

第 2 步：配置字体

import os
import matplotlib.pyplot as plt
from matplotlib import font_manager as fm

# 字体文件相对于脚本的路径
_FONT_FILE_RELATIVE = os.path.join('..', '..', 'fonts', 'BabelStoneHan.ttf')

def _get_font_path():
    """获取字体文件的绝对路径"""
    script_dir = os.path.dirname(os.path.abspath(__file__))
    font_file = os.path.join(script_dir, _FONT_FILE_RELATIVE)
    return os.path.normpath(font_file)

def setup_chinese_font():
    """配置中文字体（兼容所有 matplotlib 版本）"""
    font_file = _get_font_path()
    
    if os.path.exists(font_file):
        # 创建 FontProperties
        font_prop = fm.FontProperties(fname=font_file)
        font_name = font_prop.get_name()
        
        # 注册字体（兼容新旧版本 matplotlib）
        try:
            # 方法1：matplotlib 3.2+ 使用 addfont
            if hasattr(fm.fontManager, 'addfont'):
                fm.fontManager.addfont(font_file)
            else:
                # 方法2：旧版本 matplotlib，手动添加到字体列表
                try:
                    fm.fontManager.ttflist.append(fm.FontEntry(
                        fname=font_file,
                        name=font_name,
                        style=font_prop.get_style(),
                        variant=font_prop.get_variant(),
                        weight=font_prop.get_weight(),
                        stretch=font_prop.get_stretch(),
                        size=font_prop.get_size()
                    ))
                except Exception:
                    pass
        except Exception:
            pass
        
        # 设置全局字体
        plt.rcParams['font.family'] = font_name
        plt.rcParams['axes.unicode_minus'] = False  # 解决负号显示问题
        
        return font_prop
    
    return fm.FontProperties()

⚠️ 版本兼容性说明：

matplotlib 版本	方法	说明
≥ 3.2	`fontManager.addfont()`	推荐方法
< 3.2	`fontManager.ttflist.append()`	兼容方法

    # 创建 FontProperties
    font_prop = fm.FontProperties(fname=font_file)
    
    # 设置全局字体
    plt.rcParams['font.family'] = font_prop.get_name()
    plt.rcParams['axes.unicode_minus'] = False  # 解决负号显示问题
    
    print(f"✅ 已加载中文字体: {font_file}")
    return font_prop
else:
    print(f"⚠️ 未找到字体文件: {font_file}")
    return fm.FontProperties()

使用

chinese_font = setup_chinese_font()


---

### **第 3 步：在绑图时使用字体**

#### **方法 A：全局设置（推荐）**

```python
# 配置字体
chinese_font = setup_chinese_font()

# 绑图时自动使用全局字体
fig, ax = plt.subplots()
ax.set_title('中文标题')  # 自动使用全局字体
ax.set_xlabel('横轴标签')
ax.legend(['图例1', '图例2'])

方法 B：局部指定（精确控制）

# 配置字体
chinese_font = setup_chinese_font()

# 绑图时显式指定 fontproperties
fig, ax = plt.subplots()
ax.set_title('中文标题', fontproperties=chinese_font)
ax.set_xlabel('横轴标签', fontproperties=chinese_font)
ax.legend(['图例1', '图例2'], prop=chinese_font)

🎯 核心要点（5 个关键点）

1. 字体文件路径

# ❌ 错误：使用运行目录
font_file = os.path.join(os.getcwd(), 'fonts', 'BabelStoneHan.ttf')

# ✅ 正确：使用脚本所在目录
script_dir = os.path.dirname(os.path.abspath(__file__))
font_file = os.path.join(script_dir, '..', '..', 'fonts', 'BabelStoneHan.ttf')
font_file = os.path.normpath(font_file)  # 规范化路径

2. 显式添加字体（最关键！）

# ❌ 错误：直接创建 FontProperties
font_prop = fm.FontProperties(fname=font_file)

# ✅ 正确：先 addfont，再创建 FontProperties
fm.fontManager.addfont(font_file)  # 关键！
font_prop = fm.FontProperties(fname=font_file)

3. 设置全局字体

# 设置全局字体
plt.rcParams['font.family'] = font_prop.get_name()
plt.rcParams['axes.unicode_minus'] = False  # 解决负号显示问题

4. 使用绝对路径

# ✅ 使用 os.path.normpath() 规范化路径
font_file = os.path.normpath(font_file)

# ✅ 检查文件是否存在
if os.path.exists(font_file):
    fm.fontManager.addfont(font_file)

5. 字体文件在项目内

✅ 优点：
- 不依赖系统字体
- 可移植性好
- 跨平台兼容

❌ 避免：
- 使用系统字体路径（/usr/share/fonts/...）
- 假设字体已安装

🚨 常见问题

问题 1：中文显示为方框

原因：没有调用 addfont() 显式添加字体

解决：

# ✅ 必须先调用 addfont
fm.fontManager.addfont(font_file)
font_prop = fm.FontProperties(fname=font_file)

问题 2：负号显示为方框

原因：字体不支持负号

解决：

plt.rcParams['axes.unicode_minus'] = False

问题 3：字体路径错误

原因：使用 os.getcwd() 而不是脚本所在目录

解决：

# ✅ 使用脚本所在目录
script_dir = os.path.dirname(os.path.abspath(__file__))

问题 4：图片已生成但中文仍是方框

原因：代码修改有误或发送了旧图片

解决：

删除旧图片：rm -f output.png
重新运行脚本
检查图片修改时间：stat output.png | grep Modify

问题 6：`'FontManager' object has no attribute 'addfont'`

原因：fontManager.addfont() 是 matplotlib 3.2+ 才有的方法

解决：使用版本兼容性检查

# 兼容所有 matplotlib 版本
if hasattr(fm.fontManager, 'addfont'):
    # matplotlib 3.2+
    fm.fontManager.addfont(font_file)
else:
    # matplotlib < 3.2
    try:
        fm.fontManager.ttflist.append(fm.FontEntry(...))
    except Exception:
        pass

检查 matplotlib 版本：

import matplotlib
print(matplotlib.__version__)

问题 7：字体缓存问题

原因：matplotlib 缓存了旧字体配置

解决：

# 清除字体缓存
try:
    fm._load_fontmanager(try_read_cache=False)
except:
    pass

📊 对比总结

方案	优点	缺点	推荐度
字体文件在项目内	可移植、跨平台	需要管理字体文件	⭐⭐⭐⭐⭐
使用系统字体	无需管理文件	依赖系统、不可移植	⭐⭐
临时下载字体	自动化	网络依赖、速度慢	⭐⭐⭐

📁 Skill 包含内容

python-matplotlib-chinese-font/
├── SKILL.md                    # Skill 说明文档（本文件）
├── references/
│   ├── plot_utils.py          # 完整工具模块
│   └── test_chinese_font.py   # 测试代码
└── templates/
    └── setup_font.py          # 配置模板（可直接复制）

⚠️ 字体文件需自行下载，详见"第 0 步：下载字体文件"

📚 参考代码

完整工具模块：`references/plot_utils.py`

✅ 完整的字体配置函数
✅ 可直接导入使用
✅ 包含常用绘图参数

测试代码：`references/test_chinese_font.py`

✅ 4 种测试场景
✅ 验证中文显示是否正常
✅ 包含负数测试

配置模板：`templates/setup_font.py`

✅ 可直接复制到项目
✅ 只需修改字体路径

💡 最佳实践

# ✅ 推荐配置
import os
import matplotlib.pyplot as plt
from matplotlib import font_manager as fm

# 1. 字体路径（相对于脚本）
_FONT_FILE_RELATIVE = os.path.join('..', '..', 'fonts', 'BabelStoneHan.ttf')

# 2. 获取绝对路径
def _get_font_path():
    script_dir = os.path.dirname(os.path.abspath(__file__))
    font_file = os.path.join(script_dir, _FONT_FILE_RELATIVE)
    return os.path.normpath(font_file)

# 3. 配置字体
def setup_chinese_font():
    font_file = _get_font_path()
    
    if os.path.exists(font_file):
        fm.fontManager.addfont(font_file)  # 关键！
        font_prop = fm.FontProperties(fname=font_file)
        plt.rcParams['font.family'] = font_prop.get_name()
        plt.rcParams['axes.unicode_minus'] = False
        return font_prop
    
    return fm.FontProperties()

# 4. 使用
chinese_font = setup_chinese_font()

🔗 相关链接

BabelStone Fonts: https://www.babelstone.co.uk/Fonts/Han.html
Matplotlib Font Management: https://matplotlib.org/stable/api/font_manager_api.html
Matplotlib Chinese Font Guide: https://matplotlib.org/stable/tutorials/text/text_intro.html

📝 版本历史

版本	日期	说明
v1.0.0	2026-03-21	初始版本 - BabelStoneHan 字体配置方案
v1.1.0	2026-03-21	添加 matplotlib 版本兼容性支持
v1.2.0	2026-04-02	字体文件改为用户自行下载（满足 clawhub 文件大小限制）

Skill 创建时间：2026-03-21
维护者：太子
当前版本：v1.2.0

Files

4 total

Select a file

Select a file to preview.

Comments

Loading comments…