Node.js环境使用JS生成Excel并保存至服务器

作者:接口漫谈时间:2026-11-16 13:19:17浏览:607

深入讲解在 Node.js 服务端使用 JavaScript 构建工作簿并生成 .xlsx 文件保存至服务器本地磁盘的完整方案,涵盖 exceljs 库选型、表格样式与公式、海量数据流式写入优化以及服务端目录与权限安全实践。

在 Node.js 服务端,生成并持久化 Excel 文件(.xlsx)的核心流程是:选择适配服务端运行时且兼顾格式样式的 JavaScript 库(首选为兼具完整 API 与流式写入特性的 exceljs),在内存中初始化工作簿(Workbook)与工作表(Worksheet),注入结构化列定义与数据行,最后依托 Node.js 原生文件系统接口(fs 流或封装的 writeFile 方法)将生成的二进制数据安全写入服务器指定路径。本文将依次讲解环境依赖准备、标准化落盘编码、单元格排版修饰、超大数据量流式写入,以及服务端存储目录与权限隔离等实用经验。

Node.js环境使用JS生成Excel并保存至服务器
图 0:Node.js 环境下使用 JS 生成 Excel 并保存至服务器的基本链路

一、库选型与服务端环境搭建

在 Node.js 中生成 Excel 文件,历史上存在多个 npm 开源包,例如 xlsx(SheetJS 社区版)、exceljs 以及轻量级只写工具 json2xls。在服务端业务系统(尤其是需落盘保存为规范格式并支持自定义样式的场景)中,exceljs 几乎是最平衡且健全的选择:

  • 功能完整:对 .xlsx 格式支持完备,涵盖表头冻结、样式排版(字体、背景填色、对齐方式、边框)、数字格式化(货币、日期等)、列宽自适应。
  • 流式写入(Streaming)支持:内置专为海量数据设计的流式写入器(stream.xlsx.WorkbookWriter),能有效规避高并发或数十万行数据导致的 V8 堆内存溢出(OOM)。
  • 跨版本兼容性强:基于纯 JavaScript 实现,无原生 C++ 编译插件依赖,兼容 Linux/macOS/Windows 等各类云主机容器环境。

在项目根目录下完成初始化并安装 exceljs 依赖:

# 初始化 Node.js 项目
mkdir node-excel-saver
cd node-excel-saver
npm init -y

# 安装 exceljs
npm install exceljs
Node.js环境使用JS生成Excel并保存至服务器
图 1:Node.js 服务端生成 Excel 并落盘全流程架构图

二、基础实践:创建工作簿并直接保存至服务器磁盘

在常规体量(几百至数千行)的数据导出场景中,最直接的做法是利用 ExcelJS.Workbook 构建结构,通过 workbook.xlsx.writeFile(filePath) 异步直接写入。

Node.js环境使用JS生成Excel并保存至服务器
图 2:服务端 Excel 文件生成并落盘的四步标准化流程

以下为一个可直接执行的完整代码示例 export-basic.js:

const ExcelJS = require('exceljs');
const path = require('path');
const fs = require('fs');

async function generateAndSaveExcel() {
  // 1. 规范服务器存储目录
  const storageDir = path.resolve(__dirname, 'storage', 'reports');
  if (!fs.existsSync(storageDir)) {
    fs.mkdirSync(storageDir, { recursive: true });
  }

  // 组装带时间戳的安全文件名
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  const targetFilePath = path.join(storageDir, `order-report-${timestamp}.xlsx`);

  // 2. 创建工作簿并配置属性
  const workbook = new ExcelJS.Workbook();
  workbook.creator = 'System Server';
  workbook.lastModifiedBy = 'Data Worker';
  workbook.created = new Date();

  // 3. 添加工作表并声明列映射 (key 对应后续 row 对象的字段名)
  const worksheet = workbook.addWorksheet('订单明细表', {
    views: [{ state: 'frozen', ySplit: 1 }] // 冻结首行表头
  });

  worksheet.columns = [
    { header: '订单编号', key: 'orderId', width: 22 },
    { header: '客户名称', key: 'customerName', width: 18 },
    { header: '商品类别', key: 'category', width: 16 },
    { header: '成交金额 (元)', key: 'amount', width: 16 },
    { header: '下单时间', key: 'createTime', width: 24 }
  ];

  // 4. 填充数据行
  const sampleData = [
    { orderId: 'ORD-202611-001', customerName: '华东数码科技', category: '办公外设', amount: 4890.50, createTime: new Date() },
    { orderId: 'ORD-202611-002', customerName: '云端智慧物流', category: '网络器材', amount: 12500.00, createTime: new Date() },
    { orderId: 'ORD-202611-003', customerName: '北极星软件工程', category: '终端设备', amount: 880.00, createTime: new Date() }
  ];

  sampleData.forEach(item => {
    worksheet.addRow(item);
  });

  // 5. 格式化表头行与数值单元格
  const headerRow = worksheet.getRow(1);
  headerRow.height = 26;
  headerRow.eachCell((cell) => {
    cell.font = { name: 'Microsoft YaHei', bold: true, color: { argb: 'FFFFFFFF' } };
    cell.fill = {
      type: 'pattern',
      pattern: 'solid',
      fgColor: { argb: 'FF52677D' } // 蓝灰色底色
    };
    cell.alignment = { vertical: 'middle', horizontal: 'center' };
  });

  // 格式化金额列 (第4列) 与 日期列 (第5列)
  worksheet.getColumn('amount').numFmt = '#,##0.00';
  worksheet.getColumn('createTime').numFmt = 'yyyy-mm-dd hh:mm:ss';

  // 6. 执行写入持久化到服务器
  await workbook.xlsx.writeFile(targetFilePath);

  // 7. 设置文件系统权限 (仅文件属主可读写,遵循最小权限原则)
  fs.chmodSync(targetFilePath, 0o600);

  console.log(`[成功] Excel 文件已落盘至服务器: ${targetFilePath}`);
  return targetFilePath;
}

generateAndSaveExcel().catch(err => {
  console.error('[失败] 生成 Excel 异常:', err);
});
注意:在 Node.js 中调用 workbook.xlsx.writeFile(targetFilePath) 时,如果目标目录不存在,底层会直接抛出 ENOENT: no such file or directory 异常。因此在写入前,务必使用 fs.mkdirSync(dir, { recursive: true }) 提前补齐层级。

三、海量数据场景:基于流(Streaming)避免内存溢出

当导出数据量较小(少于 1 万行)时,默认的 new ExcelJS.Workbook() 会将所有工作表、单元格对象和样式完全保留在 V8 虚拟机的堆内存中。然而,如果需要导出 5 万至 50 万行以上的数据,内存中将生成数百万个细粒度 JavaScript 对象,这会快速把 Node.js 进程内存推高至 1.4GB 甚至 2GB 上限,引发可怕的 JavaScript heap out of memory 崩溃。

为了解决该问题,exceljs 专门提供了 流式写入接口 ExcelJS.stream.xlsx.WorkbookWriter。它的工作逻辑是:每次通过 row.commit() 提交单行数据后,该行便被序列化并推入底层的可写文件流(Writable Stream),随后立即被垃圾回收机制(GC)释放,确保整个导出过程中内存占用稳定维持在数十兆字节以内的常量级别。

Node.js环境使用JS生成Excel并保存至服务器
图 3:全量内存构建与流式管道写入在内存占用与稳定性上的核心差异

流式写入的具体实现示范 export-stream.js:

const ExcelJS = require('exceljs');
const path = require('path');
const fs = require('fs');

async function exportMassiveDataToExcel(totalRows = 100000) {
  const outputDir = path.resolve(__dirname, 'storage', 'massive');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }

  const filePath = path.join(outputDir, `audit-log-stream-${Date.now()}.xlsx`);

  // 创建流式工作簿写入器,绑定目标物理文件名
  const workbookWriter = new ExcelJS.stream.xlsx.WorkbookWriter({
    filename: filePath,
    useStyles: true // 开启基础样式支持
  });

  const worksheet = workbookWriter.addWorksheet('全量操作日志');

  // 定义列
  worksheet.columns = [
    { header: '日志ID', key: 'id', width: 14 },
    { header: '操作账号', key: 'user', width: 16 },
    { header: 'IP地址', key: 'ip', width: 20 },
    { header: '响应耗时(ms)', key: 'latency', width: 16 },
    { header: '时间戳', key: 'time', width: 22 }
  ];

  console.log(`[开始] 正在流式导出 ${totalRows} 条记录到 ${filePath}...`);

  // 模拟从数据库流式读取或分批迭代写入
  for (let i = 1; i <= totalRows; i++) {
    const row = worksheet.addRow({
      id: i,
      user: `admin_${(i % 50) + 1}`,
      ip: `192.168.1.${(i % 254) + 1}`,
      latency: Math.floor(Math.random() * 800) + 20,
      time: new Date()
    });

    // 关键:每行完成装配后立即 commit,将其从内存冲刷入文件写入缓冲区
    row.commit();

    // 周期性打印进度
    if (i % 25000 === 0) {
      console.log(`[进度] 已写入 ${i} 行...`);
    }
  }

  // 提交工作表与工作簿,关闭底层写入文件流
  worksheet.commit();
  await workbookWriter.commit();

  fs.chmodSync(filePath, 0o600);
  console.log(`[完成] 海量日志导出成功,文件大小: ${(fs.statSync(filePath).size / 1024 / 1024).toFixed(2)} MB`);
  return filePath;
}

// 模拟导出 5 万行数据
exportMassiveDataToExcel(50000).catch(console.error);

四、服务端落盘的关键防御与管理机制

将文件直接持久化至服务器磁盘,与在前端浏览器直接触发文件下载存在很大差异。在服务端持久化时,必须妥善处理文件系统安全、并发覆盖与存储配额等问题:

1. 防范路径遍历与非授权写入(Path Traversal)

若导出的文件名包含前端传入的参数(例如 req.query.filename),绝不能直接与目录进行简单拼接。恶意用户可能会传入 ../../etc/shadow 或 ../../../root/.bashrc,导致覆盖系统核心文件。

// 错误写法:直接拼接未经过滤的用户参数(高危)
const unsafePath = path.join(storageDir, req.query.filename + '.xlsx');

// 正确做法:使用 path.basename 剥离相对路径符号,或由后端统一分发唯一标识
const sanitizedBase = path.basename(req.query.filename || 'export');
const safeFileName = `${sanitizedBase.replace(/[^a-zA-Z0-9_\-\u4e00-\u9fa5]/g, '_')}_${Date.now()}.xlsx`;
const safeFilePath = path.join(storageDir, safeFileName);

2. 原子写入(Atomic Write)与并发完整性

当文件较大时,writeFile 或流式落盘需要耗费数秒时间。在此期间,若有其他服务进程(如定时同步程序、邮件发送 Worker、HTTP 下载控制器)检测到该文件已存在并尝试读取,读取到的将是残缺的破损文件。

标准解决方式是:先写入临时文件(如 filename.xlsx.tmp),在完全写完并关闭流之后,调用 fs.promises.rename 快速重命名为正式文件。在 POSIX 文件系统上,重命名操作属于原子性操作(Atomic),能确保外部消费者永远只能访问到结构完整的 Excel。

3. 文件访问权限收敛(chmod 0600)

许多服务器由多服务、多系统用户共用。生成的 Excel 常常包含企业财务、客户手机号等敏感信息。通过 Node.js 的 fs.chmodSync(filePath, 0o600) 将权限严格设为仅当前 Node.js 运行用户可读写,避免服务器上同宿主环境的其他非特权用户查看。

Node.js环境使用JS生成Excel并保存至服务器
图 4:Node.js 服务端 Excel 生成策略与安全防护决策矩阵

五、核心实践要点总结

考量维度 常规小体量场景 (< 15,000 行) 海量数据场景 (> 15,000 行)
推荐 API new ExcelJS.Workbook() new ExcelJS.stream.xlsx.WorkbookWriter()
数据行写入机制 worksheet.addRow(data) row = worksheet.addRow(); row.commit();
文件落盘触发点 最后调用 await workbook.xlsx.writeFile(path) 每行写入底层文件流,末尾调用 commit()
内存特征 (RAM) 随行数增加线性膨胀(几百 MB 至数 GB) 恒定在 30MB ~ 60MB 之间,无 OOM 隐患
目录与文件权限 提前调用 fs.mkdirSync(dir, { recursive: true }),写入后赋予 chmod 0600

综上所述,在 Node.js 服务端生成 Excel 并落盘并不是简单的“调库生成文件”,而是一个需要综合平衡 数据规模、内存峰值、文件系统写入安全以及并发访问完整性 的工程任务。通过合理选用 exceljs 的普通模型或流式管道模型,并辅以严格的文件路径校验与权限控制,即可构建出既高效又健壮的生产级报表导出系统。

作者最新文章
相关文章
更多