Node.js使用pdf-lib填充PDF表单遇模板丢失/字段未定义问题

核心错误原因 #

你读取PDF文件的方式不符合规范：PDF属于二进制格式文件，不能使用utf-8编码读取后再转字节，这一步操作已经直接损坏了PDF原始结构，是表单字段识别失败、模板内容丢失的首要原因。

其他可能的触发原因 #

• 字段名存在隐藏的前后空格或特殊字符：在Adobe中编辑字段名时，需仔细检查首尾是否有多余的不可见字符。你可以先调用form.getFields()打印所有可识别的字段名称列表，确认prodCode是否真的存在于列表中。
• Adobe保存时的兼容性问题：编辑完表单字段后保存PDF时，不要选择压缩、优化PDF选项，建议选择「另存为」，并选择兼容通用标准的PDF格式，避免Adobe生成的私有格式导致pdf-lib解析异常。
• 字段类型不匹配：如果prodCode不是文本字段（如下拉框、单选组等），调用getTextField会直接抛出找不到字段的错误，建议先打印所有字段的名称和类型做匹配校验。

修正后可运行的代码 #

const { PDFDocument } = require('pdf-lib');
const fs = require('fs');

(async () => {
    // 直接读取二进制字节，禁止转UTF-8编码
    const formPdfBytes = fs.readFileSync('./test.pdf');
  
    const pdfDoc = await PDFDocument.load(formPdfBytes)
    const form = pdfDoc.getForm()

    // 调试代码：取消注释即可打印所有可识别的字段名
    // const allFields = form.getFields()
    // console.log('所有字段名：', allFields.map(field => field.getName()))

    const productCodeField = form.getTextField('prodCode')
    const certNumberField = form.getTextField('certNumber')

    productCodeField.setText('Product code here')
    certNumberField.setText('Cert number here')

    const pdfBytes = await pdfDoc.save()
    fs.writeFileSync('./done.pdf', pdfBytes)

})().catch(e => {
  console.log(e)
});

补充说明 #

之前使用PDFescape保存后模板内容丢失，本质是PDFescape导出的PDF做了非标准的格式优化，将静态内容和表单字段做了拆分，使用错误的UTF-8编码读取时，会直接丢失静态内容部分，修正读取方式后可以规避绝大多数这类兼容问题。

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