csv-parser

概述

csv-parser（曾用名 csv-parse）是 Node.js 中处理 CSV 数据的基础库，提供高性能的 CSV 解析和生成能力。相比 csv 包更轻量，专注于解析（parse）和生成（stringify）两个核心功能。

核心特点：

• 流式解析：大文件也能低内存处理
• 自动数据类型转换（可配置）
• 支持多种输入输出格式
• 同步/异步 API 兼备

安装：

npm install csv-parser
npm install csv-stringify    # 生成 CSV

解析（csv-parser）

csv([options]) — 流式解析

const fs = require('fs')
const csv = require('csv-parser')

// 基本流式解析（适合大文件）
fs.createReadStream('data.csv')
  .pipe(csv())
  .on('data', (row) => {
    console.log(row)
    // { name: '张三', age: '25', city: '北京' }
  })
  .on('end', () => console.log('解析完成'))

常用选项

fs.createReadStream('data.csv')
  .pipe(csv({
    separator: ',',             // 分隔符（默认自动检测）
    mapHeaders: ({ header }) => header.trim(),  // 预处理表头
    mapValues: ({ value }) => value.trim(),    // 预处理单元格值
    cast: true,                 // 自动类型转换（'123'→123, 'true'→true）
    skipLines: 0,               // 跳过前 N 行
    comment: '#',               // 注释行（以 # 开头跳过）
    keepEmptyRows: false,       // 是否保留空行
    strict: false               // 严格模式（列数不一致时报错）
  }))
  .on('data', (row) => { })

同步/内存解析

const { parse } = require('csv-parse/sync')

const records = parse(inputString, {
  columns: true,
  cast: true,
  skip_empty_lines: true,
  trim: true
})
// [{ name: '张三', age: 25 }, ...]

生成（csv-stringify）

流式生成

const fs = require('fs')
const { stringify } = require('csv-stringify')

const output = fs.createWriteStream('output.csv')
const stringifier = stringify({
  header: true,
  columns: [
    { key: 'name', header: '姓名' },
    { key: 'age', header: '年龄' }
  ]
})

stringifier.write({ name: '张三', age: 25 })
stringifier.write({ name: '李四', age: 30 })
stringifier.end()
output.pipe(stringifier)

同步生成

const { stringify } = require('csv-stringify/sync')

const csvString = stringify(records, {
  header: true,
  columns: ['name', 'age', 'city']
})

完整示例

const fs = require('fs')
const { parse } = require('csv-parse/sync')
const { stringify } = require('csv-stringify/sync')

const input = fs.readFileSync('users.csv', 'utf-8')
const users = parse(input, { columns: true, cast: true, skip_empty_lines: true })
const adults = users.filter(u => u.age >= 18).map(u => ({ ...u, status: 'adult' }))
const csvOutput = stringify(adults, { header: true, columns: ['name', 'age', 'status'] })
fs.writeFileSync('adults.csv', csvOutput, 'utf-8')

常见问题