res.download

将 path 处的文件作为 "attachment" 传输。

概要

res.download(path [, filename] [, options] [, fn])

描述

Express v4.16.0 及更高版本支持可选的 options参数。

将 path 处的文件作为 "attachment" 传输。通常，浏览器会提示用户下载。默认情况下，Content-Disposition 标头 "filename=" 参数派生自 path 参数，但可以用 filename 参数覆盖。如果 path 是相对的，那么它将基于进程的当前工作目录。

下表提供了有关 options参数的详细信息。

Express v4.16.0 及更高版本支持可选的 options参数。

属性	描述	默认	可用性
maxAge	设置 Cache-Control 标头的 max-age 属性（以毫秒为单位）或 ms 格式 中的字符串	0	4.16+
lastModified	将 Last-Modified 标头设置为操作系统上文件的最后修改日期。设置 false 以禁用它。	启用	4.16+
headers	包含与文件一起服务的 HTTP 标头的对象。标题 Content-Disposition 将被 filename 参数覆盖。		4.16+
dotfiles	提供点文件的选项。可能的值为 "allow"、"deny"、"ignore"。	"ignore"	4.16+
acceptRanges	启用或禁用接受范围请求。	true	4.16+
cacheControl	启用或禁用设置 Cache-Control 响应标头。	true	4.16+
immutable	在 Cache-Control 响应标头中启用或禁用 immutable 指令。如果启用，还应指定 maxAge 选项以启用缓存。immutable 指令将阻止受支持的客户端在 maxAge 选项的生命周期内发出条件请求以检查文件是否已更改。	false	4.16+

该方法在传输完成或发生错误时调用回调函数 fn(err)。如果指定了回调函数并且发生错误，则回调函数必须通过结束请求-响应循环或将控制权传递给下一个路由来显式处理响应过程。

res.download('/report-12345.pdf')

res.download('/report-12345.pdf', 'report.pdf')

res.download('/report-12345.pdf', 'report.pdf', (err) => {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
})