CSV 转 JSON

CSV 把表格用“逗号分隔的文本行”来表示：第一行通常是列名，之后每一行都是一条记录。JSON 用“对象数组”来表示同一份表格：每个对象的键来自列名，每个对象的值来自当前这一行对应列上的单元格。把 CSV 转 JSON，本质是同一份数据换了一种排布方式——不增加信息、不丢失信息，只是从“行列”改成了“键值”。理解这一点之后，转换中遇到的问题就更容易归位：要么是源 CSV 的结构不稳，要么是字段语义需要在转 JSON 之后再额外处理一次。

为什么这个方向的转换需求格外多

CSV 是电子表格、数据导出和老系统报表通用的语言；JSON 是 HTTP 接口、配置文件和 JavaScript 运行时通用的语言。两者之间最自然的桥梁，就是把人手里编辑出来的 CSV 翻译成程序更愿意消费的 JSON：设计师交付的商品清单、分析师从 BI 工具里导出来的问卷、邮件里收到的一次性批量改动，这些场景几乎都会落到“先 CSV，再 JSON”的链路上。

决定 JSON 输出是否可信的几条规则

转换后的 JSON 可不可信，更多取决于源 CSV 在“结构层面”是否稳定，而不是某个具体值对不对。下面这几条是最关键的几个判断点。

• 第一行确实是列名：不能有空单元格、不能有重复列名、也不能是“看起来像数据的字符串”被当成了表头。
• 每一行的列数都与表头一致：多写一个逗号、漏掉一个尾部单元格，都会让后续列的值整体错位，而 JSON 看起来仍然“正常”。
• 分隔符明确且全局一致：逗号、分号、制表符任选其一，但不能这一段用逗号、那一段用分号。
• 包含分隔符、引号或换行的值需要用引号包起来；引号内的引号要用两个引号转义。这两件事任何一件没做对，下游解析都会偏。
• 编码已知且统一：UTF-8（含或不含 BOM）是跨系统交付时最稳妥的默认；混用 GBK/Big5/Latin-1 时往往是“乱码爆雷”的源头。

上面这几条只要有一条出问题，转换工具仍然会产出“合法的 JSON”，但这份 JSON 不会是你期望的那份。所以在批量信任之前，一定要看一眼开头几条和结尾几条，比对原始行列。

如何使用这个工具

1. 先在 CSV 转 JSON 中准备一份有代表性的需要转成 JSON 供接口或工具使用的 CSV 行数据，不要一开始就处理最大或最敏感的真实内容。
2. 执行处理流程并生成保留原始行列结构的 JSON 数组结果后，优先检查表头、分隔符、引号、空单元格、列宽不一致，以及文本是保持字符串还是稍后再做类型处理，再判断结果是否真的可用。
3. 只有当结果已经适合用于接口 payload 草稿、配置导入、表格清理和支持排查，并且不再触发这条风险提醒时，才复制或下载输出：如果 CSV 源内容很乱，应该先做规范化，否则异常分隔符和带引号逗号会扭曲最终 JSON 结构。

CSV 转 JSON 示例

这个 CSV 转 JSON 示例使用有代表性的需要转成 JSON 供接口或工具使用的 CSV 行数据，展示生成后的保留原始行列结构的 JSON 数组结果，便于你先确认表头、分隔符、引号、空单元格、列宽不一致，以及文本是保持字符串还是稍后再做类型处理，再把同样设置用于真实输入。

示例输入

name,email
Ada,ada@example.com

预期输出

[
  {
    "name": "Ada",
    "email": "ada@example.com"
  }
]

一份小型 CSV 与对应的 JSON

# CSV
id,name,price,inStock
1,"Notebook, A5",4.50,true
2,"Pen ""Classic""",1.20,false
3,Mug,7.00,true

# JSON
[
  { "id": "1", "name": "Notebook, A5", "price": "4.50", "inStock": "true" },
  { "id": "2", "name": "Pen \"Classic\"", "price": "1.20", "inStock": "false" },
  { "id": "3", "name": "Mug", "price": "7.00", "inStock": "true" }
]

注意 JSON 输出里所有值都是字符串。是否要把 "4.50" 转成数字、把 "true" 转成布尔，是另一个独立的决定——CSV 本身没有类型系统，所以这件事必须由消费方按业务规则显式定义，而不是默认推断。

什么时候 CSV 转 JSON 是正确选择

这一步转换最划算的场景，是“数据的下一站”是程序而不是表格，并且 CSV 本身只是一次性的中转格式。

• 用产品/QA 维护的电子表格生成单元测试或集成测试的固定数据。
• 通过一个只接受 JSON 数组的接口做一次性数据导入，省去单独写 CSV 解析器的成本。
• 用导出报表给前端 mock 服务或静态配置文件做初始化数据。
• 更仔细地检查一份 CSV：在浏览器 DevTools 里浏览 JSON，比直接读一面墙的逗号分隔文本要顺手。
• 为前端原型准备数据文件：相比再引入一个 CSV 解析依赖，直接 `fetch().then(r => r.json())` 更轻量。

容易让“顺手转一下”出事的边界

“CSV 转 JSON 翻车”的现场，通常不是工具报错，而是“JSON 完全合法、但内容已经悄悄错了”。下面这些是最常见的起爆点。

• 带换行符的字段：标准 CSV 允许引号里出现换行，但许多临时写的解析器只看 `\n`，结果一条记录会被拆成多行 JSON。
• Excel 为了强制文本而加的前导单引号（例如 `'007123`）：它们会原样进入 JSON 字符串，下游代码再去做相等比较时会突然不命中。
• 用逗号作小数点的区域（例如 `3,14`）：在逗号分隔的 CSV 里会被错切成两列。从源头切到分号分隔，比让转换工具去猜要可靠得多。
• 没有约定格式的日期字符串（例如 `03/04/2024`）：在不同地区表示完全不同的日子。转 JSON 时不要在工具里“顺手归一化”，应该先转过来、再按业务约定显式解析。
• 表头里出现了分隔符或引号：会变成无法用普通点号访问的 JSON 键名，例如 `data['price, USD']`。最好在源头先重命名表头。
• 巨型 CSV：一次性塞进内存会爆掉浏览器或脚本进程，需要走流式或分块处理，否则“整段 JSON 数组都在内存里”这件事本身就是瓶颈。

CSV 与 JSON 在表达力上的差别

使用注意

• 复用保留原始行列结构的 JSON 数组结果前，先检查表头、分隔符、引号、空单元格、列宽不一致，以及文本是保持字符串还是稍后再做类型处理。
• 如果 CSV 源内容很乱，应该先做规范化，否则异常分隔符和带引号逗号会扭曲最终 JSON 结构。
• 当结果会影响生产工作或客户可见内容时，应保留原始需要转成 JSON 供接口或工具使用的 CSV 行数据以便回退和核对。

CSV 转 JSON 参考说明

CSV 转 JSON 的参考说明应始终围绕需要转成 JSON 供接口或工具使用的 CSV 行数据、生成的保留原始行列结构的 JSON 数组结果，以及用于接口 payload 草稿、配置导入、表格清理和支持排查前必须确认的检查点。

• 输入重点：需要转成 JSON 供接口或工具使用的 CSV 行数据。
• 输出重点：保留原始行列结构的 JSON 数组结果。
• 复核重点：表头、分隔符、引号、空单元格、列宽不一致，以及文本是保持字符串还是稍后再做类型处理。

参考资料

• RFC 4180: Common Format and MIME Type for CSV Files
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• ECMA-404: The JSON Data Interchange Syntax