使用Prawn生成PDF时出现UTF-8编码InvalidByteSequenceError错误如何解决

云上老周

2026-9-27

问题根因

Encoding::InvalidByteSequenceError报错的核心原因是传入Prawn的文本包含非法UTF-8字节，你示例中PNG二进制文件的内容、读取代码文件时编码不匹配产生的乱码字节都属于这类非法内容
你用的内置Times-Roman是AFM核心字体，仅支持有限ASCII字符，无法兼容你代码里的拉丁重音字符，就算编码合法也可能出现显示异常或报错

解决方案

先清理非法UTF-8字节：不要直接用force_encoding，使用带替换规则的编码转换方法处理文本，修改报错行代码为：

pdf.text hash.keys.first.encode('UTF-8', invalid: :replace, undef: :replace, replace: ''), style: :bold

也可以用Ruby内置的scrub方法简化写法：hash.keys.first.scrub('')，直接删除所有非法UTF-8字节

过滤待导出的文件类型：导出应用代码前先筛选文件扩展名，仅处理.php、.rb、.js、.html等文本类代码文件，跳过PNG、JPG、压缩包、二进制执行文件等非文本文件，这类文件的二进制内容本身不存在可读文本，强行读取必然产生非法字节
替换兼容全字符的TTF字体：不要使用Prawn内置的AFM字体，自行加载系统安装的TTF格式字体，比如Times New Roman或开源的Noto系列字体，字体配置示例如下：

# 先注册自定义字体族
pdf.font_families.update("CustomTimes" => {
  normal: "/path/to/Times_New_Roman.ttf",
  bold: "/path/to/Times_New_Roman_Bold.ttf",
  italic: "/path/to/Times_New_Roman_Italic.ttf",
  bold_italic: "/path/to/Times_New_Roman_Bold_Italic.ttf"
})
# 全局设置使用自定义字体
pdf.font "CustomTimes"