fillpdf字段名对不上是因为其依赖PDF底层字段名而非显示标签，且大小写敏感、含隐藏字符；需用get_form_fields()确认真实字段名，避免中文及扁平化PDF。
用 fillpdf 填充 PDF 表单时，为什么字段名总对不上？
因为 fillpdf 依赖 PDF 表单的「字段名（field name）」，而这些名字往往和你在 Acrobat 里看到的「显示标签」完全不同，且大小写敏感、含隐藏字符（比如 TextField.1 或 name_001）。直接猜名字几乎必失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 先用
fillpdf.get_form_fields("form.pdf")打印出所有可填字段及其当前值，确认真实字段名 - 避免中文字段名——部分 PDF 生成器会把中文转成乱码或空字符串，
fillpdf无法识别 - 如果返回空字典，说明 PDF 是「扁平化表单」或「图像型 PDF」，
fillpdf完全无效，需换方案 -
fillpdf不支持数字签名域、下拉列表（ComboBox）或复选框（CheckBox）的值写入，只认纯文本域（Text类型）
用 pypdf（v3.0+）写入表单字段的正确流程
pypdf 从 v3.0 开始原生支持表单填写（之前版本靠 hack AcroForm 字典），但必须满足两个前提：PDF 是可编辑的 AcroForm 表单，且字段未被锁死（ReadOnly 标志为 False）。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 加载后先检查：
pdf_reader = PdfReader("form.pdf"); print(len(pdf_reader.get_fields()))，若为 0 则不是标准表单 - 填值用
pdf_writer = PdfWriter(); pdf_writer.append(pdf_reader); pdf_writer.update_page_form_field_values(page, {"field_name": "value"})，注意page是PdfReader.pages[i]对象，不是页码数字 - 字段名仍需和
get_fields()输出一致；若想批量填，遍历get_fields().keys()更可靠 - 中文内容需确保 PDF 字体嵌入了对应字形（如
SimSun），否则显示为方块——pypdf不处理字体嵌入，只写内容
填完保存后打开仍是空白？常见导出陷阱
PDF 表单填写后「视觉上没变化」，大概率是导出时未启用表单扁平化（flattening）或 PDF 阅读器缓存了旧状态。不是数据没写进去，而是没渲染出来。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
pypdf时，调用pdf_writer.write("filled.pdf")即可，无需额外 flatten —— 它默认保留交互字段 - 若需要「冻结」表单（即不可再编辑、所见即所得），得手动 flatten：
pdf_writer.flatten_annotations()，但这会丢弃所有字段结构，后续无法再修改 - 测试时别用浏览器预览 PDF，改用 Adobe Acrobat 或 Preview（macOS）——很多浏览器 PDF 插件不支持动态表单渲染
- 填完用
PdfReader("filled.pdf").get_fields()再查一次，确认字段的V（value）键已更新，这是最可靠的验证方式
什么时候该放弃自动填充，改用 OCR + 图像覆盖？
当 PDF 是扫描件（get_fields() 返回空）、表单被 Flatten、或字段是手绘矩形框+人工标注文字时，fillpdf 和 pypdf 都无能为力。
此时唯一可行路径是：定位坐标 → 渲染文字到图像层 → 合并回 PDF。工具链是 pdf2image + Pillow + img2pdf，但要注意：
- 必须用相同 DPI 转换每一页，否则文字位置偏移
- 中文字体文件（如
NotoSansCJK.ttc）要显式指定，系统字体路径在不同环境不一致 - 坐标系原点在左上角，而 PDF 的默认原点在左下角，y 值需做翻转：
y_pdf = page_height - y_image - 这种方案生成的是「图像型 PDF」，无法复制文字、不支持屏幕阅读器，仅适合归档或打印场景
字段名匹配不准、PDF 结构不规范、中文渲染缺失——这三个问题叠加时，自动化就不再是“能不能做”，而是“值不值得花半天调参”。先跑通 get_form_fields()，再决定要不要往下走。
