JavaScript使用SheetJS读取Excel文件并转换为JSON实例

一、核心解析逻辑与流转机制

利用 SheetJS 解析 Excel 文件并生成 JSON 的过程十分清晰。无论在浏览器环境还是服务端，核心逻辑均围绕三个阶段进行：获取原始二进制数据、将数据反序列化为工作簿对象（Workbook）、定位目标工作表并执行数据转换。

二、浏览器端完整实践代码

在 HTML 页面中，我们可以通过 CDN 引入 xlsx.full.min.js，或者在打包工具（Vite、Webpack）中执行 npm install xlsx。下面以原生 JavaScript 为例，演示从用户选择文件到控制台打印出 JSON 数据的完整过程。

1. HTML 与 JavaScript 代码示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>SheetJS 读取 Excel 示例</title>
  <!-- 引入 SheetJS 官方脚本库 -->
  <script src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>
</head>
<body>
  <!-- 文件上传控件 -->
  <input type="file" id="excelUploader" accept=".xlsx, .xls" />
  <pre id="jsonResult">等待上传并解析...</pre>

  <script>
    const fileInput = document.getElementById('excelUploader');
    const resultBox = document.getElementById('jsonResult');

    fileInput.addEventListener('change', async (event) => {
      const file = event.target.files[0];
      if (!file) return;

      try {
        // 第一步：将文件读取为二进制 ArrayBuffer
        const arrayBuffer = await file.arrayBuffer();

        // 第二步：通过 SheetJS 解析工作簿
        const workbook = XLSX.read(arrayBuffer, {
          type: 'array',
          cellDates: true, // 关键选项：自动将 Excel 日期序列号解析为 JS 日期对象
        });

        // 第三步：获取目标工作表（此处默认读取首个 Sheet）
        const firstSheetName = workbook.SheetNames[0];
        const worksheet = workbook.Sheets[firstSheetName];

        // 第四步：使用 sheet_to_json 将单元格网格转换为对象数组
        const jsonData = XLSX.utils.sheet_to_json(worksheet, {
          defval: '', // 空单元格默认补充为空字符串，避免字段缺失
        });

        // 渲染或消费数据
        resultBox.textContent = JSON.stringify(jsonData, null, 2);
        console.log('转换成功后的 JSON 数据：', jsonData);
      } catch (err) {
        console.error('文件解析出现异常：', err);
        resultBox.textContent = '解析失败：' + err.message;
      }
    });
  </script>
</body>
</html>

2. 输入表格与输出结果对比

假设用户上传的 Excel 工作表（Sheet1）内容如下所示：

执行 XLSX.utils.sheet_to_json(worksheet, { defval: '' }) 后输出的对应 JSON 结果为：

[
  {
    "工号": 1001,
    "姓名": "张三",
    "部门": "技术研发部",
    "入职日期": "2021-06-15T00:00:00.000Z",
    "基本工资": 15000
  },
  {
    "工号": 1002,
    "姓名": "李四",
    "部门": "产品规划部",
    "入职日期": "2022-03-01T00:00:00.000Z",
    "基本工资": 13500
  },
  {
    "工号": 1003,
    "姓名": "王五",
    "部门": "市场运营部",
    "入职日期": "2023-01-10T00:00:00.000Z",
    "基本工资": ""
  }
]

三、SheetJS 内部对象层级与数据组织

深入理解 SheetJS 的内部数据模型，有助于我们在处理复杂表格（如多 Sheet、合并单元格、表头前置空行）时游刃有余。整个数据结构呈树状展开：

四、进阶配置：控制 sheet_to_json 转换模式

在实际项目中，业务系统通常要求特定的字段命名或表格结构，XLSX.utils.sheet_to_json 提供了丰富的参数选项：

1. 改变输出格式（header 参数）

• 默认模式（不传 header）：第一行自动被当作键名，返回对象数组。
• 二维数组模式（header: 1）：包含表头在内的所有行均作为数组元素输出，返回 Array<Array<any>>。这在解析动态表头、多层表头或者需要精确保留行号时非常有用。
• 指定键名模式（header: ['fieldA', 'fieldB', ...]）：使用自定义英文属性替代表格第一行的中文文字，避免前端二次遍历重命名属性。

// 示例 A：转换为纯二维矩阵
const matrixData = XLSX.utils.sheet_to_json(worksheet, { header: 1 });
// 得到：[['工号', '姓名'], [1001, '张三'], [1002, '李四']]

// 示例 B：指定英文字段名并跳过第 1 行原中文表头
const mappedData = XLSX.utils.sheet_to_json(worksheet, {
  header: ['empId', 'empName', 'deptName', 'entryDate', 'salary'],
  range: 1, // 从索引 1（即第二行）开始解析数据
});

2. 空值与空白行处理（defval 与 blankrows）

Excel 单元格未填写时，SheetJS 默认会在生成的对象中省略该属性。如果下游代码直接解构取值，容易引发 undefined 报错。通过设置 defval: '' 或 defval: null，可确保每一个导出的对象键位完全齐整。

五、运行环境对比：浏览器与 Node.js 服务端

SheetJS 具有同构特性，在浏览器和 Node.js 运行时中 API 保持高度一致，主要区别在于输入源与底层 I/O 模块：

Node.js 服务端读取本地文件示例

const XLSX = require('xlsx');
const path = require('path');

function parseLocalExcel(filePath) {
  // 使用 XLSX.readFile 直接基于文件路径加载
  const workbook = XLSX.readFile(filePath, {
    cellDates: true,
  });

  const sheetName = workbook.SheetNames[0];
  const worksheet = workbook.Sheets[sheetName];

  // 转换为结构化数据
  return XLSX.utils.sheet_to_json(worksheet, {
    defval: null, // 服务端常习惯使用 null 表示空值
  });
}

const targetPath = path.resolve(__dirname, './data/report.xlsx');
const jsonData = parseLocalExcel(targetPath);
console.log('读取到的记录数量：', jsonData.length);

六、边界问题与数据清洗决策流程

在真实业务场景中，用户上传的 Excel 往往存在日期显示异常、多行合并表头或空行杂质。在调用 sheet_to_json 前后，建议遵循标准化的决策流程进行防御性处理：

七、总结

借助 SheetJS（xlsx），在 JavaScript 中实现 Excel 到 JSON 的转换非常轻量且高效。掌握三个关键点即可应对绝大多数业务需求：

1. 根据环境选择正确的输入载体（浏览器端借助 FileReader 读取为 ArrayBuffer，Node.js 直接使用路径或 Buffer）。
2. 在 XLSX.read 阶段开启 cellDates: true 保证日期类型准确还原。
3. 根据业务接口诉求，灵活为 sheet_to_json 设定 header（默认键、纯矩阵或指定英文字段名）与 defval 占位，产出符合规范的 JSON 实体。