Java PDFBox添加PDF附件时泰语文件名乱码如何解决

问题现象 #

开发PDF附件添加服务时，需支持泰文字符命名的附件，但实操中出现文件名乱码问题：

• 调用fs.setFileUnicode()方法添加附件时，泰文文件名显示错位、缺字
• 改用fs.setFile()方法时，文件名完全无法识别，乱码程度更严重

根因分析 #

两个方法的编码逻辑不符合PDF规范要求，是乱码的核心原因：

• fs.setFile()默认采用PDF早期版本定义的PDFDocEncoding字符集，该字符集仅覆盖基础拉丁字符与常用符号，无泰文对应码点，传入泰文文件名时必然出现严重乱码。
• fs.setFileUnicode()虽然设计目标是支持Unicode文件名，但多数PDF操作库的低版本实现存在bug：未按照PDF 1.7规范要求将文件名字段转为带BOM头的UTF-16BE编码，而是直接写入UTF-8编码字节，泰文属于Unicode高位区段字符，解析端按规范解码时就会出现字符错乱。

修复方案 #

按优先级选择以下方案即可解决问题：

1. 升级依赖的PDF操作库至最新稳定版
   目前主流PDF库（iText 7.x、PDFBox 2.x+、PDFLib 9.x+）的最新版本已经修复了Unicode附件文件名的编码bug，升级后直接调用fs.setFileUnicode()传入原始泰文文件名即可正常显示，无需额外编码处理，同时兼容中文、阿拉伯文等所有非拉丁语系文件名。
2. 无法升级依赖时手动做编码适配
   按照PDF规范手动处理文件名编码后再传入方法，核心逻辑是给文件名添加UTF-16BE格式的BOM标识，再转码为对应字节流，避免被类库错误转码。以Java环境为例，参考代码如下：

   import java.nio.ByteBuffer;
   import java.nio.charset.StandardCharsets;
   
   // 原始泰文文件名
   String originalThaiName = "เอกสารแนบ.pdf";
   // 拼接UTF-16BE BOM头 + 编码后的文件名
   byte[] bom = new byte[]{(byte) 0xFE, (byte) 0xFF};
   byte[] nameBytes = originalThaiName.getBytes(StandardCharsets.UTF_16BE);
   byte[] standardPdfName = ByteBuffer.allocate(bom.length + nameBytes.length)
           .put(bom)
           .put(nameBytes)
           .array();
   // 以ISO-8859-1编码转成字符串传入，避免字节丢失
   fs.setFileUnicode(new String(standardPdfName, StandardCharsets.ISO_8859_1));
   

3. 兼容性校验
   附件写入完成后，可检查PDF附件字典中的UF字段值，确认该字段存储的是符合规范的Unicode文件名，避免类库在写入过程中做二次错误转码。

注意：不要通过字符替换、音译转写的方式规避乱码，这类方案会破坏文件名原始语义，在不同PDF阅读器（Adobe Acrobat、浏览器内置阅读器、WPS、移动端阅读器）下兼容性极差。

内容的提问来源于stack exchange，提问作者Kauê Oliveira