Node.js中使用exceljs流式导出大型Excel触发502超时问题咨询

• 假流式实现：当前代码根本没有做到边读边写，knexPromise({}) 默认会把符合条件的全量数据一次性从数据库拉取到Node内存，大表场景下这一步往往要耗时1-2分钟。这期间虽然你已经设置了200状态码和响应头，但没有任何实际的响应字节完成传输，连接处于纯空闲状态。
• 网关空闲超时的硬限制：大多数团队的服务前面都有云SLB、API网关这类中间层，这类网关的空闲超时是平台固定配置（常见阈值就是2分钟），根本无法自定义修改。哪怕你把Nginx的超时调到10分钟，只要连接上有超过2分钟没有数据传输，网关就会直接掐断连接返回502——这也是你调了Nginx超时还是卡在2分钟触发错误的根本原因。
• 无背压控制的写入：即便数据已经拉到内存中，同步的forEach循环会一口气把所有行塞给exceljs的写流，遇到系统写缓冲区占满时，数据会堆在内存里等待写入，进一步拉长数据向外传输的间隔，放大空闲断连的风险。
• 格式配置错误：当前用的是xlsx格式的WorkbookWriter，但响应头的Content-Type还是老版本xls的类型，文件名后缀也和实际格式不匹配，这个问题不影响超时，但会导致浏览器打开导出文件时出现格式异常。

核心思路是实现真·边读边写，保证响应建立后持续有数据向外传输，永远不出现超过网关阈值的空闲期。

• 尽早发送响应头，不要等任何数据库查询完成后再发。只要把状态码、响应头写入响应流，网关就会和Node服务保持活跃连接。
• 把knex的全量查询换成游标流式查询，每次只从数据库拉固定数量的行到内存，拉到就立刻写入excel流，全程不把全量数据加载到内存。
• 调整写入逻辑，每收到一行数据库返回的结果，就立刻提交写入excel，保证数据向外传输的连续性。

修正后的参考实现：

const specification_abc_xyz = [
  { header: "", key: "index", width: 6 },
  { header: "1", key: "name", width: 120 },
  { header: "2", key: "share", width: 23 },
  { header: "3", key: "cum_share", width: 25 },
  { header: "4", key: "coeff", width: 29 },
  { header: "5", key: "abc", width: 10 },
  { header: "6", key: "xyz", width: 10 },
];

// 立刻发送响应头，不要等待任何数据库查询完成
res.status(200);
res.setHeader("Content-disposition", "attachment; filename=db_dump.xlsx");
// 修正为xlsx对应的标准Content-Type
res.setHeader("Content-type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");

const options = {
  stream: res,
  useStyles: false,
  useSharedStrings: false,
};
const workbook = new Excel.stream.xlsx.WorkbookWriter(options);
const worksheet = workbook.addWorksheet("Tutorials");
worksheet.columns = specification_abc_xyz;

let rowIndex = 0;
// 替换为knex的流式游标查询，highWaterMark控制单次拉取的行数，一般1000-2000行比较合适
const dbStream = knexPromise({})
  .select("name", "share", "cum_share", "coeff", "abc", "xyz")
  .stream({ highWaterMark: 1000 });

// 每收到一行数据就立刻写入excel流，保证持续有数据回传
dbStream.on("data", (row) => {
  row.index = ++rowIndex;
  worksheet.addRow(row).commit();
});

// 数据库读取完成后，提交excel写入流并结束响应
dbStream.on("end", async () => {
  worksheet.commit();
  await workbook.commit();
  res.end();
});

// 必须加错误监听，避免流异常导致进程崩溃或响应挂死
dbStream.on("error", (err) => {
  console.error("导出失败", err);
  res.end();
});

• 整个导出流程从响应建立开始，每隔几十毫秒就会有新的字节流回传到网关，连接永远不会因为空闲超时被掐断，完全不需要调整任何上游的超时配置。
• 内存占用稳定在几十MB级别，哪怕导出百万行的大文件，也不会因为内存溢出导致进程卡顿。
• 数据库查询和excel写入是并行执行的，总导出耗时比原来的全量拉取模式更短。

内容的提问来源于stack exchange，提问作者Fatdrfrog