本文详解如何用现代、活跃维护的 pdf-lib 库正确填充含重复字段名、多选项复选框（如 cms-1500 表单）的 pdf 表单，规避 pdf.js 不支持表单写入的限制，并提供可直接运行的完整代码示例。
本文详解如何用现代、活跃维护的 pdf-lib 库正确填充含重复字段名、多选项复选框（如 cms-1500 表单）的 pdf 表单，规避 pdf.js 不支持表单写入的限制，并提供可直接运行的完整代码示例。
PDF 表单自动化填充在医疗、金融、政务等场景中需求广泛，但实际落地常遇两大痛点：一是表单字段命名不规范（如多个复选框共用同一 name 但不同 exportValues），二是误选技术栈导致功能不可用。值得注意的是，pdf.js 是纯渲染/读取库，官方明确不支持表单编辑与保存（参见其 FAQ：“Is it possible to add annotations to a PDF?” → 答案是否定的）。因此，将 pdf.js 用于填表属于根本性技术误用——它能读取字段、修改内存状态，但 saveDocument() 和 getData() 均忽略表单变更，仅返回原始字节流。
真正可靠的方案是使用 pdf-lib（v1.17.0+，当前活跃维护），它专为 PDF 写入设计，且已原生支持 AcroForm 字段的深度操作。针对问题中 employment.employment 这类“同名多值复选框组”，关键在于绕过高层 getTextField()/getCheckBox() 的名称匹配逻辑，转而通过底层 AcroForm API 精准定位并操作字段实例。
以下为推荐实现流程（Node.js 环境）：
import { PDFDocument, PDFName } from 'pdf-lib';
// 1. 加载 PDF
const pdfBytes = fs.readFileSync('form-cms1500.pdf');
const pdfDoc = await PDFDocument.load(pdfBytes);
// 2. 获取表单对象（自动解析 AcroForm）
const form = pdfDoc.getForm();
// 3. 获取所有字段（保留原始顺序与结构）
const allFields = form.acroForm.getAllFields();
// 4. 定位目标复选框（例如：第32个字段，对应 'employment' 组中的 'YES' 选项）
// 注意：索引需根据实际字段顺序确定（建议先 console.log(allFields.map(f => f.getName())) 调试）
const targetCheckbox = allFields[32]; // 类型为 PDFField，非 PDFCheckBox（避免类型误判）
// 5. 设置值：复选框需使用 getOnValue() 获取其激活值（如 'Yes', 'ON', '1'），而非硬编码字符串
if (targetCheckbox instanceof PDFName) {
// 若字段为 PDFName（极少见），需转换
targetCheckbox.setValue(PDFName.from('Yes'));
} else {
targetCheckbox.setValue(targetCheckbox.getOnValue());
}
// 6. 保存修改后的 PDF
const modifiedPdfBytes = await pdfDoc.save();
fs.writeFileSync('filled-cms1500.pdf', modifiedPdfBytes);✅ 关键要点说明：
- form.acroForm.getAllFields() 返回的是原始字段数组（含所有 PDFField 子类实例），不受字段名去重影响，完美解决 employment.employment 多实例识别问题；
- 复选框/单选按钮必须调用 .getOnValue() 获取其预设的“选中态值”（如 'YES'），直接设 'On' 或 'true' 将无效；
- 切勿依赖 form.getCheckBox('fieldName') —— 当存在同名多字段时，它仅返回第一个匹配项；
- 浏览器环境需配合 pdf-lib 的 saveAs 工具或 Blob 下载，而非 fs 模块。
⚠️ 注意事项：
- 确保 PDF 表单为 AcroForm 格式（非 XFA），pdf-lib 不支持 XFA 表单；
- 若字段被禁用（setReadOnly(true)）或设为只读，需先调用 field.setReadOnly(false)；
- 中文内容需嵌入支持 Unicode 的字体（如 Noto Sans CJK），否则可能显示为方块；
- 生产环境务必添加异常处理（如 try/catch 包裹 PDFDocument.load 和 save）。
综上，面对复杂 PDF 表单填充任务，请坚定选择 pdf-lib 作为核心工具，并善用其底层 AcroForm API 进行精准控制。放弃 pdf.js 的填表幻想，不仅能避免数小时调试陷阱，更能获得稳定、可维护、符合标准的输出结果。
