python-matplotlib-chinese-font

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

📌 问题描述

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

控制台警告：

UserWarning: Glyph XXXXX missing from current font

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

🎯 使用场景

当以下情况时使用此 Skill：

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

🚀 快速开始

第 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()

⚠️ 版本兼容性说明：

# 创建 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：全局设置（推荐）**

配置字体

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：图片已生成但中文仍是方框**

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

**解决**：
1. 删除旧图片：`rm -f output.png`
2. 重新运行脚本
3. 检查图片修改时间：`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