如何把掃描文件轉成 CSV

你手邊有一疊紙本——發票、收據、送貨單——而你需要把它們變成試算表裡的一列列資料。手動重新打字又慢又容易出錯，而一般的 OCR 工具只會吐出一大片原始文字，後續還是得自己拆解成欄位。你真正想做的其實更聚焦、也更實用：把一份文件的照片或掃描檔，每次都穩定地轉成乾淨的一列 CSV，正確的值落在正確的欄位裡。

這篇教學帶你完成的就是這件事。欄位只需定義一次，把 space-ocr 對準一張影像，每份文件就會自動填成一列。完成後，你把整張表匯出成 CSV——採用帶位元組順序標記（BOM）的 UTF-8，讓 Excel 與中日韓文字都能正常開啟。不必重打，而且每個值都能回溯到它在頁面上的位置。

整個流程的樣貌

把掃描文件轉成 CSV，可拆成四個動作：

1. 拍照或掃描你的文件——點陣影像（JPEG、PNG、TIFF 等）。用手機拍就行，自動旋轉會處理拍歪的照片。
2. 欄位只定義一次——把你在意的欄位命名好（vendor、date、total、明細項目……）。這會成為每份文件據以判讀的結構。
3. 上傳——每張影像被判讀後，值會落進你欄位下的新一列。不需要逐份設定。
4. 匯出 CSV——把整張表下載成 <sheetName>.csv，到哪都能打開。

好處在於一致性：因為欄位事先就固定了，第十張收據落下的樣子會和第一張一模一樣。

先看證據：每個值都知道自己從哪來

進入步驟之前，先說明為什麼這值得信賴。把滑鼠移到下方任一欄位上——收據上的方框會標示出那個值正是從哪個位置讀取的，而且每個欄位都帶有一個比對比例（match ratio）。一份 CSV，只有當裡面的數字都經得起查核時才有用，而在這裡，每一格都能回溯到來源像素。

如何把掃描文件轉成 CSV，一步步來

1. 把文件拍成影像

space-ocr 判讀的是點陣影像——JPEG、PNG、GIF、BMP、TIFF 與 WebP。把收據放桌上拍、把發票掃成 PNG，或從掃描軟體匯出頁面都可以。掃描 PDF 也可以直接丟進應用程式，每一頁都會自動轉成影像。用手機斜著拍也沒問題：引擎會讀取 EXIF 方向資訊並校正旋轉，所以拍歪的照片照樣能正向判讀，值也照樣錨定在正確的位置。

2. 欄位只定義一次

這一步正是把 OCR 變成整齊表格的關鍵。建立一張帶有欄位結構的表——也就是你想當成 CSV 標題的那些欄位。純量欄位是單一值（vendor、invoice_date、total）；陣列欄位則用來收納會重複出現的明細項目。這個只需定義一次，之後你上傳的每份文件都會依照同一組欄位來判讀。

vendor        (string)
invoice_date  (string)
total         (string)
items         (array) → name, unit_price, qty

如果你不想手動建立結構，內建範本（invoice、receipt、business_card 等）會替常見的文件類型提供現成的欄位與提示。發票的部分，可參考從發票擷取明細項目。

3. 上傳——列會自動填好

欄位就緒後，把影像上傳到這張表。每份文件成為一列：引擎判讀頁面，把每個值塞進對應的欄位下。丟進二十張收據，你就得到二十列，全都同一個樣子。明細項目陣列會以結構化的子項目保留在該列底下，匯出時即可展開。

值是原樣（verbatim）回傳的——7,855 的逗號會保留，全形字元與敬稱也都原封不動——所以你的 CSV 反映的是紙上實際印出的內容，而不是重新格式化後的猜測。

4. 匯出成 CSV

點下匯出，這張表就會下載成 <sheetName>.csv。標題列直接由你的結構建構而成：

• 開頭一個 # 欄（列索引）。
• 每個純量欄位名稱照原樣呈現。
• 每個陣列子項目攤平為 colName.childName——所以含 name 與 unit_price 的 items 陣列會產生 items.name 與 items.unit_price 兩欄。

含有明細項目陣列的列會展開成子列——父層的純量值出現一次，每個明細項目在其底下各佔一列，所以一張有八行明細的發票會變成同一個廠商與日期下的八列 CSV。檔案以帶位元組順序標記（BOM）的 UTF-8 寫入，正是這一點讓 Excel——以及日文、韓文或中文——打開時不會出現亂碼。

如果你手動編輯過某一格，匯出時你的手動值會覆蓋原本的 OCR 值，所以更正會一路反映到 CSV 裡。

透過 API 來做

同一套流程也能在無介面（headless）情況下完成。建立一張帶欄位的表，把影像上傳上去，再用 GET /view 取回結構化的列——這是在伺服器端進行的，不會重跑 OCR，也不會計費。從這裡你可以自行寫出 CSV，或直接抓取該表的 CSV 匯出。GET /view 還讓你在匯出前先篩選（where）、排序並選取欄位，所以你只需輸出真正需要的那幾列。

列進來之後，GET /view 會以結構化 JSON 回傳，你可以直接寫成 CSV——或交給你的會計系統。關於擷取端點與欄位規格的完整說明，請參考發票資料擷取 API 指南以及 API 文件。

掃描 PDF 與輸入格式的提醒

space-ocr 的引擎處理的是點陣影像，而非 PDF 位元組——不過在應用程式裡你不需要操心這件事：把掃描 PDF 丟進來，每一頁都會在 OCR 之前自動點陣化成影像。只有當你直接呼叫公開 API 時，才需要先把每一頁轉算成影像（PNG 或 JPEG）再上傳。如果你的目標明確是 Excel 而不是 CSV，同樣這套流程依舊適用——詳見把掃描 PDF 轉成 Excel。CSV 是阻力最小的目標：到哪都打得開，而帶 BOM 的 UTF-8 匯出也代表編碼不會出意外。