PyMuPDF insert_textbox无法使用自定义字体与粗体，如何正确应用非默认字体？

问题描述 #

使用PyMuPDF的page.insert_textbox()向现有PDF插入文本时，文本插入功能正常，但自定义字体与粗体样式完全无法生效：

• 显式设置自定义.ttf字体或使用"helv-bold"/"times-bold"时，PyMuPDF要么静默回退到Helvetica字体，要么因字体名称不属于核心内置PostScript字体抛出错误；
• 自行映射粗体/斜体后，粗体文本仍无法正常显示。

相关代码 #

status = page.insert_textbox(
    rect,
    text,
    fontsize=fs,
    fontname=fontname,        # 自定义字体或"helv-bold"失效
    align=0,
    color=text_color
)

简化后的包装函数：

def fit_text_in_rect(page, rect, text, font_size, fontname, text_color=None, bold=False):
    status = page.insert_textbox(
        rect,
        text,
        fontsize=font_size,
        fontname=fontname,   # 自定义字体在此失效
        color=text_color,
        align=0,
    )

已尝试方法 #

• 使用内置字体名称（helv、times、courier）：仅能渲染常规样式；
• 尝试PostScript名称（Helvetica-Bold、Times-Bold）：仍无法显示粗体；
• 传递fitz.Font(fontfile=...)注册的.ttf路径：insert_textbox()拒绝使用；
• 插入文本前手动嵌入字体：仍被忽略；
• 查阅PyMuPDF问题文档，寻找粗体/自定义字体的限制说明。

预期与实际行为 #

预期行为 #

1. 插入文本时使用自定义.ttf/.otf字体；
2. 按要求正确渲染粗体/斜体。

实际行为 #

1. PyMuPDF静默回退到Helvetica字体；
2. 无论使用何种方法，均无法显示粗体样式；
3. 非核心字体导致insert_textbox()报错。

疑问与解答 #

1. insert_textbox()是否支持自定义字体？ #

不支持。insert_textbox()的fontname参数仅接受PyMuPDF预定义的核心PostScript字体名（如"helv"、"times"），且仅支持这些字体的常规样式，无法直接使用自定义字体或粗体变体。

2. 向现有PDF插入文本时，如何嵌入并使用自定义.ttf字体？ #

使用fitz.TextWriter API，这是PyMuPDF处理自定义字体的标准方案，会自动嵌入字体到PDF中：

# 加载自定义字体
custom_font = fitz.Font(fontfile="path/to/your/font.ttf")
# 创建TextWriter对象
tw = fitz.TextWriter(page.rect)
# 将文本填充到指定矩形（自动换行、对齐）
tw.fill_textbox(rect, text, font=custom_font, fontsize=font_size, color=text_color, align=0)
# 将文本写入页面
tw.write_text(page)

3. 是否存在可行的方法生成粗体文本？ #

有两种可靠方式：

• 直接加载对应的粗体字体文件（如xxx-bold.ttf），通过TextWriter插入；
• 若无单独粗体字体文件，可通过fitz.Font的bold参数强制开启粗体（仅对支持的TrueType字体有效）：

bold_font = fitz.Font(fontfile="path/to/regular-font.ttf", bold=True)

4. 正确的PyMuPDF工作流程是什么？ #

放弃使用insert_textbox()，改用TextWriter API，这是PyMuPDF处理自定义字体、特殊样式文本的推荐方案。无需手动嵌入字体，write_text()方法会自动完成字体嵌入。如果需要使用内置字体的粗体变体，也可通过TextWriter加载对应字体对象：

# 加载内置Helvetica粗体
bold_helv = fitz.Font("helv", bold=True)
tw = fitz.TextWriter(page.rect)
tw.fill_textbox(rect, text, font=bold_helv, fontsize=font_size, color=text_color)
tw.write_text(page)

内容的提问来源于stack exchange，提问作者JaS