因为excel文件是zip压缩的xml结构包，fs.readfile读出的是二进制乱码，json.parse会报syntaxerror；node原生不支持解析，必须用xlsx或exceljs等第三方库处理结构和映射。

为什么直接用 fs.readFile 读 Excel 文件会失败

Excel 文件（.xlsx）不是纯文本，而是 ZIP 压缩的 XML 结构包。用 fs.readFile 读出来是一堆二进制乱码，JSON.parse 必然报错 SyntaxError: Unexpected token in JSON at position 0。Node 原生不支持解析 Excel，必须借助第三方库处理文件结构和单元格映射。

选 xlsx 还是 exceljs？看你的导出需求

xlsx（SheetJS）轻量、纯 JS、无依赖，适合只读 + 简单转 JSON；exceljs 功能全（支持样式、公式、流式写入），但体积大、API 更重。日常导出结构化数据，优先用 xlsx：

Wjs Localizing Video

用于端到端视频本地化流程的轻量编排器，路由至四个专注子技能——/wjs-transcribing-audio、/wjs-translating-subtitles...

下载

• 安装：npm install xlsx
• 读取后默认返回 Workbook 对象，需手动提取第一个 sheet 的数据：workbook.Sheets[workbook.SheetNames[0]]
• 用 XLSX.utils.sheet_to_json 转成数组，它默认跳过空行、合并单元格会被忽略（这点容易漏数据）
• 若首行是表头，加 { header: 1 } 得到二维数组；加 { header: 'A' } 可按列字母生成键名

导出 JSON 时字段名丢失或错位的常见原因

Excel 表头含空格、特殊字符、重复名，或第一行不是表头——都会导致 sheet_to_json 生成的 key 不符合预期。实际操作中建议：

• 先用 XLSX.utils.sheet_to_json(sheet, { header: 1 }) 拿到原始二维数组，人工检查前几行
• 若第一行是表头，再用 sheet_to_json(sheet, { header: 1, defval: null })，避免空单元格被跳过
• 手动清洗 key：遍历结果数组，对每个对象的 key 做 .trim().replace(/\s+/g, '_').toLowerCase()
• 注意日期列：默认转成 JS Date 对象，JSON 序列化后变成字符串（如 "2024-03-15T00:00:00.000Z"），如需时间戳或自定义格式，得提前处理

VSCode 中调试时中文乱码或路径报错怎么办

Windows 下 VSCode 终端默认编码可能是 GBK，而 Node 读文件默认用 UTF-8，会导致中文路径或内容读取失败。解决方式很直接：

• 确保 Excel 文件保存为 UTF-8 兼容格式（其实 .xlsx 本身是二进制，但路径含中文时，Node 的 fs 在 Windows 上可能因 locale 出问题）
• 在 VSCode 设置里搜 terminal.integrated.env.windows，添加："PYTHONIOENCODING": "utf-8"（虽是 Python 相关项，但影响终端环境变量）
• 更稳妥的做法：用绝对路径，且路径字符串前加 r（Node 不支持 raw 字符串，所以改用双反斜杠或正斜杠）：const filePath = 'C:/data/input.xlsx';
• 运行前加一句 console.log(require('fs').existsSync(filePath));，确认路径真实存在——VSCode 工作区根目录 ≠ 当前脚本所在目录

真正卡住人的地方往往不是库怎么用，而是 Excel 文件本身有合并单元格、空行插在中间、或者表头跨了两行——这些情况 sheet_to_json 默认不处理，得自己切片、补空、重映射。别急着封装函数，先用 console.log 把 sheet 对象打出来看结构。