Express的POST路由调用res.download返回文件不触发下载弹窗如何解决？

服务端排查点 #

• 确认zip.writeZip是同步方法/等待异步写入完成
  你当前的写法默认writeZip是同步操作，若该方法为异步回调/ Promise 类型，文件还没写入完成就调用res.download会触发异常。如果是异步方法请调整为等待写入完成后再执行下载逻辑，示例：

// 若为Promise类型
async function onArchiveCompleted (res, zip) {
    const archive = `${uuidv4()}.zip`
    await zip.writeZip(archive) // 等待写入完成
    res.download(archive)
}

• 补充必要响应头避免被覆盖
  res.download默认会自动设置Content-Disposition和Content-Type头，若你之前的逻辑中设置了其他响应头（比如application/json）会覆盖默认配置，可以手动指定头避免异常：

function onArchiveCompleted (res, zip) {
    const archive = `${uuidv4()}.zip`
    zip.writeZip(archive)
    // 手动设置响应头
    res.setHeader('Content-Disposition', `attachment; filename="${archive}"`)
    res.setHeader('Content-Type', 'application/zip')
    res.download(archive)
}

• 确认文件路径正确
  res.download传相对路径时，路径是相对于Node进程的运行目录，建议使用绝对路径避免找不到文件的问题：

const path = require('path')
function onArchiveCompleted (res, zip) {
    const archive = path.resolve(__dirname, `${uuidv4()}.zip`)
    zip.writeZip(archive)
    res.download(archive)
}

客户端排查点（90%以上的该类问题都是这个原因） #

如果你是使用fetch/axios等AJAX方式调用POST接口，浏览器默认不会自动触发下载弹窗，哪怕响应内容正确也需要手动处理Blob数据触发下载，示例代码：

// axios示例
axios.post('/your-api-path', postParams, {
  responseType: 'blob' // 必须指定响应类型为blob，否则二进制内容会乱码
}).then(res => {
  // 生成临时链接触发下载
  const blob = new Blob([res.data], { type: 'application/zip' })
  const downloadUrl = window.URL.createObjectURL(blob)
  const aTag = document.createElement('a')
  aTag.href = downloadUrl
  aTag.download = 'archive.zip' // 自定义下载文件名
  document.body.appendChild(aTag)
  aTag.click()
  // 清理临时资源
  window.URL.revokeObjectURL(downloadUrl)
  document.body.removeChild(aTag)
})

如果不需要无刷新提交，也可以直接用原生form表单提交POST请求，浏览器会自动处理下载逻辑，无需额外JS代码。

其他注意事项 #

• res.download执行后不要再调用其他响应返回方法（比如res.json、res.send），一次请求只能返回一次响应，多次调用会冲突。
• 确认接口没有配置跨域头限制，如果是跨域请求需要开放Content-Disposition头的访问权限，否则前端拿不到文件名配置。

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