pdfplumber比PyPDF2更适合表格提取，因其基于PDF图形对象重建坐标与表格边界，能识别真实结构；而PyPDF2仅输出无结构的断裂文本。
pdfplumber 为什么比 PyPDF2 更适合表格提取
PyPDF2 只能读取原始文本流，遇到跨页表格、合并单元格或带边框的 PDF 表格时，输出是断裂的、无结构的字符串。而 pdfplumber 底层基于 PDF 的图形对象（lines、rects、chars）重建文本坐标和表格边界，能识别真实表格结构。
实操建议：
- 安装时用
pip install pdfplumber，它自动依赖pdfminer.six，无需额外装 - 打开 PDF 后优先调用
page.extract_table()而不是page.extract_text()，前者返回二维列表，后者只是字符串 - 如果表格线不清晰，加参数
vertical_strategy="text"或horizontal_strategy="text"让它按文字对齐推断列/行 - 注意：含扫描件（图片型 PDF）的文档，
pdfplumber会直接返回空表——必须先 OCR，不能跳过这步
处理合并单元格和多页表头的典型写法
真实财务或报表 PDF 常见第一行是总标题、第二行是栏位名、第三行起才是数据，且“金额”列可能纵向合并了 5 行。直接 extract_table() 会把合并单元格拆成多个空行。
解决路径：
立即学习“Python免费学习笔记（深入）”；
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 先用
page.find_tables()[-1]定位最可能的目标表格（通常最后一个 table 对象是主数据区） - 对每个
table对象，检查其cells属性，遍历所有cell的top/bottom/left/right坐标，手动合并垂直方向重叠的 cell - 表头跨页时，不要依赖单页
extract_table()，改用page.crop((x0, y0, x1, y1)).extract_table()精确裁剪出表头区域单独解析 - 示例：若第 2 页表头和第 3 页数据逻辑连续，需先拼接两页的
chars列表，再统一做表格检测
当 pdfplumber 提取结果为空或错乱时怎么排查
常见错误现象：page.extract_table() 返回 None，或返回的 list 每行只有 1–2 个元素，明显漏列。
优先检查这几处：
- 用
page.to_image().save("debug.png")导出页面图像，确认 PDF 是否为扫描件（如果是，立刻停用pdfplumber，换pytesseract + pdf2image - 打印
len(page.chars)，若为 0，说明 PDF 文字被加密或嵌入为矢量路径（如某些银行 PDF），此时需用fitz.Page.get_text("dict")（PyMuPDF）尝试提取 - 检查 PDF 版本：PDF 1.7+ 中使用「Tagged PDF」结构的文档，
pdfplumber解析更稳；旧版若含大量浮动文本框，需加layout_mode="normal" - 临时启用调试模式：
pdfplumber.open("x.pdf", debug=True)，它会在控制台输出每页的 lines/rects 数量，快速判断是否检测到表格线
导出为 DataFrame 时保留原始格式的关键点
直接 pd.DataFrame(table) 会丢失数字类型、日期格式、千分位符号，后续清洗成本高。
推荐做法：
- 先用
table = page.extract_table() or []获取原始二维列表，再逐行处理：对疑似数字列，用re.sub(r"[^\d.-]", "", cell.strip())清洗后再float() - 日期列若含“2024年03月”这类中文格式，别急着转
datetime，先存为字符串，后续用pandas.to_datetime(..., format="%Y年%m月") - 避免用
pd.read_csv(StringIO(...))中转——CSV 解析器会自动跳过空格、合并连续逗号，破坏原始对齐 - 如果目标是 Excel 输出，用
df.to_excel(..., index=False, header=False)并传入engine="openpyxl"，否则默认 engine 会丢样式信息
表格识别不是“开箱即用”的过程，坐标偏移 1px、字体嵌入方式不同、PDF 生成工具差异，都可能导致同一段脚本在两个看似相同的 PDF 上表现迥异。与其堆参数，不如先用 page.to_image(resolution=150).draw_rects(page.rects) 可视化检测结果，看它到底“看见”了什么。
