空表格导出(204):你的 PDF 多半没有列
PDF 转 Excel 与 PDF 转 CSV 在检测不到表格块时返回 HTTP 204,这是有意为之,不是崩溃,也不是让你把同一文件原样重试。

PDF 转 Excel 或 PDF 转 CSV 跑完返回 HTTP 204 No Content、没有下载正文,说明抽取器找到的表格块为零。这个状态是故意的:版式启发式看不到列时,API 拒绝凭空造一份空电子表格。
抽取器在找什么
两个工具共用同一条流水线。服务器执行 pdftotext -layout,按换页符切分页面,再把看起来像列块的行归组。一行里出现至少两个连续空格(layout 模式的列槽),就算表格式行。一个块至少要有两行这样的行才会被保留;孤零零一行带空格的文字会被丢掉,免得标题变成只有一行的“表”。
PDF 转 CSV(POST /api/v1/convert/pdf/csv)为每张检测到的表输出一份 CSV,文件名带上页号与表序号,有多张时就打成 ZIP。PDF 转 Excel(POST /api/v1/convert/pdf/xlsx)写一个工作簿,每张检测到的表占一个工作表。
当这个列表为空,两者都返回映射到 204 的 Output::no_content()。带空白 .xlsx 的 200 更容易被误当成成功;204 的意思是“没有可导出的东西”。
拿到 204 的常见原因
- 纯散文 PDF:叙述性文字,没有清晰的列对齐。改用 PDF 转文本 或 PDF 转 Markdown。
- 没有文本层的扫描页:
pdftotext输出为空,自然看不到表。先跑 OCR 并选可搜索 PDF 输出,只有当那些词确实排成列时,才对这份 PDF 重试导出。 - 只用线条或图片画出的表:没有可抽取单元格文字的视觉网格,不会变成工作表。
- 混乱的多栏杂志版式:启发式可能漏掉人眼叫“表”的块,或者把阅读顺序拼得很糟。
- 只有一行的“表”:一行带空格永远成不了块,至少要两行表格式行。
加密文件在抽取前需要授权的 解锁。文件损坏、获取信息或导出都打不开时,用 修复。
204 不是什么
204 不是传输失败,不是超时,也不是“服务器忘了带附件”。把它当成一个成功的判断:没有表格块。不改文本层或版式就原样重试同一份文件,只会再得到 204。脚本应当按状态码分支,而不是看文件名是否为空。
来自 OCR 的 Markdown 是给 Agent 的文本抽取,不是电子表格。把 OCR 输出粘进 .md 文件之后仍然需要列,你依然得有一份 pdftotext -layout(或人眼)能看出列槽的版式;对没有文本层的同一份扫描 PDF 再导一次,还是 204。
接下来做什么
- 打开 PDF,确认单元格文字能选中。选不中就先 OCR,再判断恢复出来的文字是否足够列状,能过这套启发式。
- 预期有多张表时优先 PDF 转 Excel(每表一个工作表);想要单个平面文件或一堆 CSV 打包,则优先 PDF 转 CSV。
- 页面是叙述体,就换工具;表格导出只会一直返回 204。
- 给 Agent 或流水线写状态处理时,把 204 映射成“未检测到表”,而不是一个通用重试循环。
- 只要文字,就停在 PDF 转文本 或 PDF 转 Markdown;硬把散文塞进电子表格形状,只会继续 204。
浏览器路径不需要账号。同一批端点走 HTTP 见 开发者。客户端可能 POST 两次时,重试请带 Idempotency-Key(Idempotency-Key)。