Next.js页面Excel数据导出功能在生产环境失效问题排查

问题描述 #

在Next.js应用页面中，从MongoDB获取如下格式的对象数组数据：

const data = [
    { _id: '63769f3609144b01779e75e6', name: '', email: '', description: 'Visitor' },
    { _id: '6375b7b609144b01779e75c9', name: '', email: '', description: 'Resident (Homeowner),Businessowner,Work in the City' }
]

使用XLSX包实现按钮点击导出Excel功能，触发函数代码如下：

import * as XLSX from 'xlsx';

// ...其他代码
const handleExcelExport = () => {
    const wb = XLSX.utils.book_new()
    const ws = XLSX.utils.json_to_sheet(data)
    XLSX.utils.book_append_sheet(wb, ws, "Comments");
    XLSX.writeFile(wb, "survey-data.xlsx");
}

该功能在开发环境正常，但部署到Heroku生产环境后，下载的Excel文件提示损坏无法打开；改为xls扩展名后虽能打开，但内容显示异常。

解决步骤 #

• 强制指定XLSX输出格式
  默认情况下XLSX.writeFile可能会根据文件名自动推断格式，但生产环境的环境差异可能导致推断错误，手动指定bookType参数确保输出标准XLSX格式：

  XLSX.writeFile(wb, "survey-data.xlsx", { bookType: "xlsx" });
  

• 预处理空字段
  数据中的空字符串（如name、email字段）可能导致Excel解析异常，预处理数据将空值替换为占位符或null：

  const processedData = data.map(item => ({
    ...item,
    name: item.name || "无",
    email: item.email || "无"
  }));
  const ws = XLSX.utils.json_to_sheet(processedData);
  

• 调整Next.js打包配置
  Next.js的生产打包优化可能会对XLSX库造成影响，在next.config.js中添加配置确保库被正确转译：

  module.exports = {
    transpilePackages: ['xlsx'],
  };
  

• 改用Blob手动触发下载
  部分生产环境的浏览器或CDN对XLSX.writeFile的底层实现支持不佳，改用Blob生成下载链接的方式：

  const handleExcelExport = () => {
    const wb = XLSX.utils.book_new();
    // 预处理数据
    const processedData = data.map(item => ({
      ...item,
      name: item.name || "无",
      email: item.email || "无"
    }));
    const ws = XLSX.utils.json_to_sheet(processedData);
    XLSX.utils.book_append_sheet(wb, ws, "Comments");
    
    // 生成Blob并创建下载链接
    const wbout = XLSX.write(wb, { bookType: 'xlsx', type: 'blob' });
    const url = URL.createObjectURL(wbout);
    const downloadLink = document.createElement('a');
    
    downloadLink.href = url;
    downloadLink.download = "survey-data.xlsx";
    document.body.appendChild(downloadLink);
    downloadLink.click();
    
    // 清理临时资源
    setTimeout(() => {
      document.body.removeChild(downloadLink);
      URL.revokeObjectURL(url);
    }, 100);
  }
  

• 校验Heroku环境配置

  1. 在package.json中指定与本地开发一致的Node.js版本：

     "engines": {
       "node": ">=18.x"
     }
     

  2. 确保xlsx依赖在dependencies中，而非devDependencies，避免生产环境未安装该库。

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