把扫描文档转成 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. 上传——行自己填好

列就位之后，把图片上传到这张表。每份文档变成一行：引擎读取页面，把每个值放进对应的列下。丢进二十张收据，你就得到二十行，形状完全一致。明细行数组会作为该行的结构化子项保留下来，导出时随时可以展开。

值是原样返回的——7,855 里的逗号保留、全角字符和敬称也一并保留——所以你的 CSV 反映的是页面上印的内容，而不是被重新格式化过的猜测。

4. 导出为 CSV

点击导出，表会下载为 <sheetName>.csv。表头行直接由你的列结构生成：

• 开头一列 #（行号）。
• 每个标量列名按原样列出。
• 每个数组子字段展平为 colName.childName——所以一个带 name 和 unit_price 的 items 数组会生成 items.name 和 items.unit_price 两列。

包含明细行数组的行会展开成多个子行——父级的标量值出现一次，每条明细行在其下面各占一行，于是一张有八条明细的发票就变成八行 CSV，共享同一个供应商和日期。文件以带字节序标记（BOM）的 UTF-8 写出，正是这个 BOM 让 Excel——以及日文、韩文、中文——打开时不会出现乱码。

如果你手动改过某个单元格，导出时你手填的值会覆盖原始 OCR 值，所以修正会一路体现到 CSV 里。

用 API 来做

同样的流程也可以无界面地跑。先建一张带列的表，往里上传图片，再用 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 导出意味着不会有编码上的意外。