How-to約 1 分鐘閱讀

空白表格匯出(204):你的 PDF 大概沒有欄

PDF 轉 Excel 與 PDF 轉 CSV 在偵測不到表格區塊時回傳 HTTP 204,這是刻意設計,不是當機。掃描件先 OCR;純散文 PDF 會一直空白。

By the PDF123 team · Updated 2026-10-02
空白表格匯出(204):你的 PDF 大概沒有欄

如果 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()。回 200 加上一份空白的 .xlsx,更容易被誤讀成成功;204 的意思是「沒有東西可以匯出」。

拿到 204 的常見原因

  • 純散文 PDF:敘事性文字,沒有清楚的欄位對齊。請改用 PDF 轉文字 或 PDF 轉 Markdown。
  • 沒有文字層的掃描頁:pdftotext 輸出是空的,自然看不到表格。先跑 OCR 並選擇可搜尋的 PDF 輸出,而且只有在那些字確實排成欄時,才對這份 PDF 重試匯出。
  • 只用線條或影像畫出的表格:視覺上看得到格線,卻沒有可抽取的儲存格文字,不會變成工作表。
  • 雜亂的多欄雜誌版面:啟發式可能漏掉人眼稱為「表格」的區塊,或把閱讀順序併得很糟。
  • 只有單列的「表格」:一行帶空白的文字永遠成不了區塊,至少要有兩行表格式資料。

加密檔案在抽取前需要經過授權的 解鎖。如果取得資訊或匯出都打不開檔案,請用 修復 PDF 修好損壞的檔案。

204 不是什麼

204 不是傳輸失敗、不是逾時,也不是「伺服器忘了帶附件」。請把它當成一個成功的判斷:沒有任何表格區塊。不改文字層或版面就原樣重試同一份檔案,只會再得到 204。腳本應該依狀態碼分支,而不是看檔名是否為空。

來自 OCR 的 Markdown 是給 Agent 的文字抽取,不是試算表。把 OCR 輸出貼進 .md 檔案之後,如果還需要欄位,你依然得有一份 pdftotext -layout(或人眼)看得出欄間距的版面;對沒有文字層的同一份掃描 PDF 再匯出一次,還是會回 204。

接下來做什麼

  1. 打開 PDF,確認儲存格文字可以選取。選不中就先用 OCR,再判斷還原出來的文字夠不夠「像欄」,能不能過這套啟發式。
  2. 預期有多張表格時,優先 PDF 轉 Excel(每張表一個工作表);想要單一平面檔案或一堆 CSV 打包,則優先 PDF 轉 CSV。
  3. 如果頁面是敘事體,就換工具;表格匯出只會一直回傳 204。
  4. 給 Agent 或管線寫狀態處理時,把 204 對應成「未偵測到表格」,不要做成通用的重試迴圈。
  5. 如果你只要文字,就停在 PDF 轉文字 或 PDF 轉 Markdown;硬把散文塞進試算表的形狀,只會繼續得到 204。

瀏覽器路徑不需要帳號。同一批端點走 HTTP 見 開發者。如果你的用戶端可能 POST 兩次,重試時請帶 Idempotency-Key(Idempotency-Key)。

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool