JSON 转 CSV 完整指南 - 转换技巧与最佳实践（2026）

📖 为什么需要 JSON 转 CSV 完整指南？#

在实际工作中，简单的 JSON 转 CSV 可能遇到各种复杂情况：

嵌套的 JSON 结构如何处理？
特殊字符（逗号、引号、换行）怎么转义？
大型数据集如何优化性能？
不同编码格式如何选择？

本指南将详细解答这些问题，让你成为 JSON 转 CSV 的专家。

🔍 JSON 与 CSV 格式对比#

数据结构差异#

JSON（JavaScript Object Notation）：

✅ 支持复杂嵌套结构
✅ 支持多种数据类型
✅ 自描述性（字段名包含在内）
❌ 不适合表格数据展示

CSV（Comma-Separated Values）：

✅ 简单的表格格式
✅ Excel 原生支持
✅ 文件体积小
❌ 只支持二维数据

转换挑战#

graph TD A[JSON 数据] --> B{数据结构} B -->|扁平数组 | C[直接转换] B -->|嵌套对象 | D[扁平化处理] B -->|数组嵌套 | E[展开或合并] B -->|混合类型 | F[类型统一] C --> G[CSV 输出] D --> G E --> G F --> G

📝 转换规则详解#

1. 扁平 JSON 转换#

最简单的情况：

输入：

1
[
2
  {"name": "张三", "age": 25, "city": "北京"},
3
  {"name": "李四", "age": 30, "city": "上海"}
4
]

输出：

1
name,age,city
2
张三，25，北京
3
李四，30，上海

2. 嵌套对象处理#

方案 A：点号表示法（推荐）

输入：

1
[
2
  {
3
    "name": "张三",
4
    "address": {
5
      "city": "北京",
6
      "district": "朝阳"
7
    }
8
  }
9
]

输出：

1
name,address.city,address.district
2
张三，北京，朝阳

方案 B：JSON 字符串

1
name,address
2
张三，"{\"city\":\"北京\",\"district\":\"朝阳\"}"

3. 数组处理#

方案 A：展开为多行

输入：

1
{
2
  "name": "张三",
3
  "skills": ["JavaScript", "Python", "Java"]
4
}

输出：

1
name,skill
2
张三，JavaScript
3
张三，Python
4
张三，Java

方案 B：合并为字符串

1
name,skills
2
张三，"JavaScript,Python,Java"

4. 特殊字符转义#

CSV 转义规则：

字符	转义方式	示例
逗号	用引号包裹	`"Hello, World"`
双引号	doubling	`"He said ""Hi"""`
换行符	用引号包裹	`"Line1\nLine2"`
制表符	用引号包裹	`"Col1\tCol2"`

示例：

1
[
2
  {
3
    "quote": "He said \"Hello, World!\"",
4
    "multiline": "Line 1\nLine 2"
5
  }
6
]

转换为：

1
quote,multiline
2
"He said ""Hello, World!""","Line 1
3
Line 2"

🛠️ 高级转换技巧#

1. 字段筛选#

只导出需要的字段：

1
// 原始 JSON
2
[
3
  {
4
    "id": 1,
5
    "name": "产品 A",
6
    "price": 100,
7
    "cost": 50,
8
    "profit": 50
9
  }
10
]
11

12
// 只导出部分字段
13
// 输出：name,price,profit
14
// 产品 A,100,50

2. 字段重命名#

1
// 映射规则
2
{
3
  "user_name": "Username",
4
  "user_email": "Email"
5
}
6

7
// 转换
8
{"user_name": "张三", "user_email": "zhangsan@example.com"}
9
// 输出：Username,Email
10
// 张三，zhangsan@example.com

3. 数据格式化#

数值格式化：

1
// 保留 2 位小数
2
{
3
  "price": 99.999
4
}
5
// 输出：99.99

日期格式化：

1
// ISO 日期 → 本地格式
2
{
3
  "created_at": "2026-01-01T00:00:00Z"
4
}
5
// 输出：2026-01-01

货币格式化：

1
// 添加货币符号
2
{
3
  "amount": 1000
4
}
5
// 输出：¥1,000.00

4. 空值处理#

1
// 策略选择
2
{
3
  "name": "张三",
4
  "age": null,
5
  "email": ""
6
}
7

8
// 方案 1：保留空值
9
// 张三，,
10

11
// 方案 2：填充默认值
12
// 张三，0,N/A
13

14
// 方案 3：跳过该字段
15
// 张三

📊 性能优化#

1. 大数据量处理#

分块处理：

1
// 100000 条数据
2
const batchSize = 10000;
3
for (let i = 0; i < data.length; i += batchSize) {
4
  const batch = data.slice(i, i + batchSize);
5
  convertToCSV(batch);
6
}

流式处理：

1
// 边读边写，节省内存
2
readStream
3
  .pipe(transform)
4
  .pipe(writeStream);

2. 编码优化#

UTF-8 with BOM（推荐用于 Excel）：

1
const csvWithBOM = '\uFEFF' + csvContent;

压缩输出：

1
// 对于超大文件
2
const compressed = pako.gzip(csvContent);

3. 性能对比#

数据量	普通转换	优化后	提升
1,000 条	50ms	30ms	40%
10,000 条	500ms	200ms	60%
100,000 条	5s	1.5s	70%
1,000,000 条	50s	12s	76%

💼 实战案例#

案例 1：电商订单导出#

需求：将订单 API 的 JSON 响应转为 CSV，供财务对账。

原始数据：

1
{
2
  "orders": [
3
    {
4
      "id": "ORD001",
5
      "customer": {"name": "张三", "phone": "138****1234"},
6
      "items": [
7
        {"product": "iPhone", "price": 7999, "qty": 1}
8
      ],
9
      "total": 7999,
10
      "status": "completed"
11
    }
12
  ]
13
}

处理步骤：

提取 orders 数组
扁平化 customer 对象
展开 items 数组
格式化金额

最终 CSV：

1
order_id,customer_name,customer_phone,product,price,quantity,total,status
2
ORD001，张三，138****1234,iPhone,7999,1,7999,completed

案例 2：用户数据迁移#

需求：从 MongoDB 导出用户数据，导入 MySQL。

MongoDB 数据：

1
[
2
  {
3
    "_id": "507f1f77bcf86cd799439011",
4
    "username": "zhangsan",
5
    "profile": {
6
      "realname": "张三",
7
      "avatar": "https://..."
8
    },
9
    "created_at": "2026-01-01T00:00:00Z"
10
  }
11
]

目标 CSV：

1
id,username,realname,avatar,created_at
2
507f1f77bcf86cd799439011,zhangsan，张三，https://...,2026-01-01

案例 3：日志数据分析#

需求：将 JSON 格式的日志转为 CSV，在 Excel 中分析。

日志数据：

1
[
2
  {
3
    "timestamp": 1704067200000,
4
    "level": "INFO",
5
    "message": "User login",
6
    "context": {
7
      "userId": 123,
8
      "ip": "192.168.1.1"
9
    }
10
  }
11
]

CSV 输出：

1
timestamp,level,message,userId,ip
2
2026-01-01 00:00:00,INFO,User login,123,192.168.1.1

🎯 最佳实践#

1. 数据验证#

转换前检查：

1
function validateJSON(data) {
2
  // 检查是否为数组
3
  if (!Array.isArray(data)) {
4
    throw new Error('JSON 必须是数组格式');
5
  }
6

7
  // 检查字段一致性
8
  const keys = Object.keys(data[0]);
9
  for (let item of data) {
10
    if (Object.keys(item).sort().join(',') !== keys.sort().join(',')) {
11
      console.warn('字段不一致');
12
    }
13
  }
14
}

2. 错误处理#

1
try {
2
  const csv = convert(json);
3
} catch (error) {
4
  if (error instanceof SyntaxError) {
5
    console.error('JSON 格式错误');
6
  } else if (error.message.includes('escape')) {
7
    console.error('特殊字符转义失败');
8
  }
9
}

3. 测试用例#

1
// 边界测试
2
const testCases = [
3
  { input: [], expected: '' },
4
  { input: [{}], expected: '\n' },
5
  { input: [{a: 1}], expected: 'a\n1' },
6
  { input: [{a: ','}], expected: 'a\n","' },
7
];

❓ 常见问题#

Q1: 如何保留前导零？#

答：在字段前添加制表符或使用文本格式：

1
id
2
\t00123

Q2: CSV 文件在 Excel 中乱码？#

答：

使用 UTF-8 with BOM 编码
或在 Excel 中使用”数据→从文本导入”
选择正确的编码（UTF-8）

Q3: 数字精度丢失？#

答：

大数字用引号包裹："123456789012345"
或添加制表符：\t123456789012345

Q4: 如何处理动态字段？#

答：

1
// 收集所有字段
2
const allKeys = new Set();
3
data.forEach(item => {
4
  Object.keys(item).forEach(key => allKeys.add(key));
5
});
6
// 使用 allKeys 作为表头

🚀 工具推荐#

在线工具：

XingDian JSON to CSV - 功能全面
ConvertCSV - 批量转换
JSON to CSV Pro - 高级功能

编程库：

JavaScript: json2csv
Python: pandas
Node.js: csv-stringify