JSON 转 CSV 完全指南

什么时候需要 JSON 转 CSV？

JSON 是程序间数据交换的理想格式，但对于数据分析、报表制作和业务用户来说，CSV（逗号分隔值）或 Excel 格式更为直观。常见的 JSON 转 CSV 需求场景：从 API 提取数据后导入 Excel 进行分析；将数据库查询结果（JSON 格式）转换为可分享的电子表格；将产品数据或用户数据导出供非技术人员处理；数据迁移工作中将 JSON 格式数据导入到 CSV 格式的目标系统。

JSON 转 CSV 的前提条件

CSV 是纯表格结构（行×列），而 JSON 是树状结构（可以任意嵌套）。JSON 能成功转换为 CSV 的前提：JSON 最外层是一个数组；数组中每个元素是结构相同的对象；对象的字段名将成为 CSV 的列标题；对象的字段值将成为对应行的单元格数据。

如果 JSON 包含嵌套对象或数组，就需要决定如何"展平"（Flatten）这些嵌套结构。不是所有 JSON 数据都适合直接转换为 CSV，深度嵌套的 JSON 可能需要先手动提取所需字段再转换。

简单 JSON 数组转 CSV 示例

// JSON 输入 / JSON Input
[
  {"id": 1, "name": "Alice", "age": 30, "city": "Beijing"},
  {"id": 2, "name": "Bob", "age": 25, "city": "Shanghai"},
  {"id": 3, "name": "Carol", "age": 28, "city": "Guangzhou"}
]

// CSV 输出 / CSV Output
id,name,age,city
1,Alice,30,Beijing
2,Bob,25,Shanghai
3,Carol,28,Guangzhou

嵌套 JSON 的展平策略

对于嵌套对象，通常用点号连接路径作为列名：

// 嵌套 JSON / Nested JSON
{"name": "Alice", "address": {"city": "Beijing", "zip": "100000"}}

// 展平后 CSV 列名 / Flattened CSV column names
name, address.city, address.zip

对于嵌套数组，处理更复杂，常见策略有：将数组序列化为 JSON 字符串放在单个单元格中（保留完整数据但牺牲可读性）；将数组展开为多行（每个数组元素一行，父行数据重复）；只取数组第一个或某几个元素（丢弃部分数据）。需要根据具体业务需求选择最合适的策略。

Python 中的 JSON 转 CSV

import json, csv

# 读取 JSON
with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 写入 CSV
if data:
    with open('output.csv', 'w', newline='', encoding='utf-8-sig') as f:
        writer = csv.DictWriter(f, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)

注意使用 utf-8-sig 编码（带 BOM），可以确保 Excel 正确识别中文字符，避免乱码。如果是英文数据，使用普通 utf-8 即可。

JavaScript/Node.js 中的转换

const { Parser } = require('json2csv');

const fields = ['id', 'name', 'age', 'city'];
const opts = { fields };

try {
  const parser = new Parser(opts);
  const csv = parser.parse(jsonData);
  console.log(csv);
} catch (err) {
  console.error(err);
}

CSV 格式注意事项

生成 CSV 时需要注意以下细节：字段值包含逗号：该值需要用双引号括起来，如 "New York, USA"；字段值包含双引号：双引号需要转义为两个双引号，如 "Say ""hello"""；字段值包含换行：整个值需要用双引号括起来；分隔符选择：某些地区（如德语区）用分号代替逗号作为分隔符，Excel 在这些区域可能无法正确识别逗号分隔的 CSV。

对于国际化数据，建议使用制表符（TSV 格式）而不是逗号作为分隔符，可以避免大多数分隔符冲突问题。

在线 JSON 转 CSV 工具推荐

在线 JSON 转 CSV 工具的选择建议：优先选择在本地浏览器处理数据的工具（避免敏感数据上传到第三方服务器）；确认工具支持自定义字段选择（不是所有 JSON 字段都需要导出）；验证工具能正确处理中文和特殊字符（有些工具对非 ASCII 字符支持不好）；检查是否支持嵌套结构的展平处理。

对于大文件（数万行以上的 JSON），在线工具可能速度较慢或内存溢出，建议使用命令行工具（如 jq + 自定义脚本）或 Python 脚本处理。