JSON 转 CSV 的核心差异：从嵌套结构到扁平表格
这个页面的独特之处在于，它处理的是从一种带类型、可嵌套的数据格式向一种纯文本表格的逆向转换。JSON 支持对象、数组、数字、布尔值和 null，可以任意嵌套；CSV 则是一种无类型的扁平表格——没有嵌套层级，没有数据类型，也没有多工作表。转换过程中，所有类型信息、嵌套结构、数据格式全部丢失。为了把嵌套的 JSON 对象表示成 CSV 的扁平行列，工具使用点路径表示法将对象键名扁平化（例如 address.city 表示原 JSON 中 { "address": { "city": "北京" } } 的字段）。对象数组会展开成表格行，而数组的数组则直接以内层数组为行。因为 CSV 使用分隔符，嵌入值中的逗号和换行符必须用双引号包裹——工具自动处理这种引用，但数字的前导零会丢失。在转换前，你需要决定嵌套字段如何表示（工具默认使用点路径）。
JSON 和 CSV 的结构差异与转换方法
JSON 是分层结构，一个顶层数据可以包含多个嵌套的对象和数组。CSV 只有行和列，每行是一条记录，每列是一个字段，所有值都是字符串。要把 JSON 转为 CSV，必须确定一个“基准”来展开：
- 对象数组（
[ { "name": "张三", "age": 30 }, { "name": "李四", "age": 25 } ]）：每个对象变成一行，对象的键变成列名。如果对象内有嵌套对象（如{ "address": { "city": "北京" } }），嵌套键会以点路径形式展开为独立列：address.city、address.street等。 - 数组的数组（
[ [ "张三", 30 ], [ "李四", 25 ] ]）：每个内层数组变成一行，数组元素按顺序成为列的值。此时没有显式的列名，工具会按顺序编号或不生成列名。 - 非表格形状的 JSON：如果 JSON 既不是对象数组也不是数组的数组（例如一个简单的
"hello"或一个嵌套的对象但不是数组包裹），工具无法推断行列结构，会显示错误信息：“This JSON is invalid or not table‑shaped.”。
扁平化的关键：点路径表示法
当你有一个如下的 JSON 时：
{
"id": 1,
"name": "张三",
"contact": {
"phone": "13800138000",
"email": "zhangsan@example.com"
},
"orders": [
{ "item": "书", "price": 45 },
{ "item": "笔", "price": 3 }
]
}
转换时，contact.phone 和 contact.email 会变成两列。而 orders 是数组，如果数组中的每个对象被认为是独立行，则工具会将整个 JSON 当作多个行合并表处理，这取决于具体的扁平化策略。实际操作中，如果顶层是单个对象，工具会将其转换为单行表格；如果顶层是对象数组，每个对象的嵌套字段各自展开。点路径符号是业界常见的做法（如 MongoDB 的字段投影语法、Logstash 的格式化工具），但要注意：字段名中的句点会被解释为嵌套分隔符，原始 JSON 中 "a.b" 这样的字段名可能会被错误拆分——不过大多数情况下不常见。
数据类型丢失与 CSV 引用规则
CSV 没有类型系统。转换时，数字、布尔值和日期会保留其类型，而嵌套对象会展平为带点的列名。
| 原始 JSON 值 | CSV 单元格内容 |
|---|---|
123 |
123 |
true |
true |
null |
（空字符串） |
3.14 |
3.14 |
"张三" |
张三 |
- 前导零丢失：数字
00123在 JSON 中会被视为数字123（如果未加引号），CSV 输出是123；如果 JSON 中"00123"是字符串，则 CSV 输出保留00123。所以如果你需要保留前导零，原始 JSON 应使用字符串类型。 - CSV 引用：当值中包含分隔符（如逗号）、换行符或双引号时，工具会用双引号包裹整个值，并将值中的双引号替换为两个双引号。例如值
他说："好"会变成"他说：""好"""。 - 嵌入换行符：如果 JSON 字符串中包含
分隔符的选择与影响
CSV 的“C”本意是逗号，但实际场景中常用其他分隔符。工具提供三个选项：
| 分隔符 | 适用场景 |
|---|---|
| 逗号 (,) | 英语地区的默认 CSV 格式；大多数表格软件直接识别 |
| 分号 (;) | 欧洲许多国家因小数点用逗号，习惯用分号作为 CSV 分隔符（如 Excel 本地化版本） |
| 制表符 (\t) | 用于 TSV 格式；避免值和分隔符混淆，但有些软件无法自动识别 |
选择分隔符时，注意值中是否含有该字符。如果你数据中逗号很多，用分号或制表符可减少引用包裹，但输出文件字段名可能也需调整。工具不会自动识别你文件内的分隔符冲突，由你自行判断。
客户端处理的隐私优势
所有处理都在浏览器中完成：你上传的 JSON 文件被读取到内存，在浏览器内解析、扁平化、生成 CSV，最后触发下载。工具声称“nothing is uploaded to any server”——实际上不经过任何网络请求。这对隐私敏感的场景（如包含个人身份信息、商业数据的 JSON）非常重要。缺点是不能处理超大文件：工具会检查文件大小并显示“This file is too large. Use a file under ‹max›.”的报错。文件大小限制为 8 MB。工具也限制了行列数：最多 10,000 行和 200 列。如果转换时间超过大约 12 秒，工具会停止并显示“这次转换耗时太久，请换一个更小的文件。”。
常见错误与限制
- 文件类型错误：工具只接受 CSV、JSON 或 XLSX 文件。如果拖入其他文件，显示“Choose a CSV, JSON or XLSX file.”。
- 输出格式冲突：如果选择与输入相同的格式，显示“Choose a different output format.”。
- 转换超时：如果转换时间超过约 12 秒，工具会停止转换并显示“这次转换耗时太久，请换一个更小的文件。”。
- 无法转换：非表格结构或解析错误时，显示“Could not convert this file.”。用户可手动取消（“Conversion cancelled.”）。
常见问题 FAQ
问：我的 JSON 文件包含 {"users": [... ]}，为什么转换失败？
答：顶层是对象而不是数组。工具需要的是对象数组（如 [ {"name":"张三"},... ]）或数组的数组。如果你的 JSON 是 {"users": [...]}，需要先提取 users 数组再上传。
问：转换后的 CSV 中，嵌套对象字段会变成 address.city 这样的列名，我可以控制吗？
答：工具默认使用点路径表示法，不支持自定义分隔符或扁平化策略。如果需自定义，可先用正则替换 JSON 中的嵌套结构，或使用脚本处理。
问：为什么数字 0123 变成了 123？
答：JSON 中不加引号的数字 0123 被视为十进制数，解析后为 123。要保留前导零，必须在 JSON 中写为字符串 "0123"。JSON 规范本身不支持前导零的数字。
问：文件处理安全吗？ 答：全部在浏览器本地操作，不经过服务器。即使离线也能工作（前提是页面已加载）。但注意关闭浏览器后内存中的文件消失。
问：转换后 CSV 中的 null 为什么是空字符串？
答：CSV 没有 null 概念。工具将 JSON 的 null 表示为空单元格。如果需保留“null”文本，需在 JSON 中使用字符串 "null"。
问：我上传的 JSON 是数组的数组但没有列名，能自动生成吗？ 答：工具不会生成列名，输出 CSV 的第一行就是第一个数组元素的值。如需列名，请将数据改为对象数组。