Express 4.16.4中res.download下载文件重命名失效问题

我之前也碰到过同款坑，在Express 4.x版本里res.download()的第二个参数不生效，通常是这几个原因导致的：

1. 前端<a>标签未指定download属性 #

如果你的前端<a>标签只是单纯用href指向下载接口，部分浏览器会优先取URL路径里的最后一段（也就是你的:facture参数值）作为文件名，直接忽略后端返回的Content-Disposition头里的文件名。

解决办法：
给<a>标签加上download属性，值可以设为空（让后端决定文件名）或者直接指定你想要的文件名：

<a href="/downloadfacturemaintenance/your-filename.png" download>下载文件</a>
<!-- 或者更明确地指定 -->
<a href="/downloadfacturemaintenance/your-filename.png" download="facture.png">下载文件</a>

2. 浏览器缓存了旧的响应头 #

如果之前已经请求过这个接口，浏览器可能缓存了旧的Content-Disposition头，导致新的文件名无法生效。

解决办法：

• 先强制刷新浏览器缓存（Ctrl+F5）测试；
• 后端主动添加禁止缓存的响应头，确保每次请求都获取最新的配置：

router.get("/downloadfacturemaintenance/:facture", function (req, res) {
  var facture = req.params.facture;
  // 添加禁止缓存的头
  res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
  res.setHeader('Pragma', 'no-cache');
  res.setHeader('Expires', '0');
  
  res.download(path.join(__dirname, '../config/uploads/facture_maintenance/'+facture), "facture.png", function (err) {
    if (err) {
      console.error("下载出错:", err);
      res.status(500).send("下载失败");
    }
  });
});

3. 中间件覆盖了响应头 #

如果你的Express应用里有其他中间件（比如静态文件中间件、自定义的响应处理中间件），可能在res.download()之后修改了Content-Disposition头，把你设置的文件名给覆盖了。

解决办法：

• 检查中间件执行顺序，确保下载路由的处理逻辑在可能修改响应头的中间件之前；
• 可以手动设置Content-Disposition头，用res.sendFile替代res.download，更可控：

router.get("/downloadfacturemaintenance/:facture", function (req, res) {
  var facture = req.params.facture;
  const filePath = path.join(__dirname, '../config/uploads/facture_maintenance/'+facture);
  
  // 手动设置响应头
  res.setHeader('Content-Disposition', `attachment; filename="facture.png"`);
  res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
  
  res.sendFile(filePath, function (err) {
    if (err) {
      console.error("下载出错:", err);
      res.status(500).send("下载失败");
    }
  });
});

4. 文件路径拼接问题（可能性较低） #

虽然你用了path.join()，但还是要确认拼接后的路径是否正确，确保文件确实存在。如果文件不存在，res.download()可能会返回错误，浏览器就会 fallback 到URL里的文件名。

解决办法：
在代码里打印拼接后的路径，检查是否正确指向存在的文件：

const filePath = path.join(__dirname, '../config/uploads/facture_maintenance/'+facture);
console.log("文件路径:", filePath); // 验证这个路径是否正确

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