HexaPDF 0.20.2版本起Windows11下填充AcroForm报字形缺失错误

问题现象 #

使用HexaPDF处理带AcroForm的PDF文件时，通过如下代码填充表单字段：

@acro_form.field_by_name(fieldname).field_value = value

版本与环境表现差异如下：

• 0.20.1及更早版本功能运行正常
• 升级至0.20.2版本后，生成文档时抛出错误：HexaPDF::Error (Glyph for "2" missing)
• 报错触发规律：所有数字、除a、b、c之外的所有小写字母，都会触发对应字符的字形缺失同类错误
• 环境差异：问题仅在Windows 11开发环境出现，Linux环境运行无异常

问题原因 #

0.20.2版本调整了AcroForm字段填充时的字体自动匹配逻辑，Windows平台下系统字体枚举优先级和Linux存在差异，自动匹配时会优先选中仅包含少量字形的子集字体（通常是PDF内嵌入的子集字体、或者系统内仅支持部分基础字符的装饰类字体），未正确加载覆盖全量数字、小写字母的可用字体，导致不在该子集字体内的字符找不到对应字形抛出错误。

解决方法 #

二选一即可修复问题：

1. 显式指定AcroForm使用的标准字体，跳过自动匹配逻辑。填充字段前设置全局默认外观字体，示例：

   # 设置AcroForm默认字体为内置支持全量ASCII字符的Helvetica
   @acro_form.default_appearance_string.font = 'Helvetica'
   

2. 加载/初始化文档时关闭新增的字体自动回退配置，保持和0.20.1版本一致的字体查找逻辑，示例：

   # 读取已有文档时传入配置
   doc = HexaPDF::Document.open('your_file.pdf', acro_form: { font_fallback: false })
   @acro_form = doc.acro_form
   

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