PHP force_download下载PDF时指定文件名不生效始终为file.pdf

问题描述 #

调用force_download函数实现文件下载时，生成的PDF文件内容正常，但下载得到的文件名始终为file.pdf，并非代码中指定的Daily_delivery_sheet.pdf。同文件内另一个功能函数使用完全相同的代码逻辑，可正常输出指定文件名的下载文件。
相关实现代码：

$pdf = $mcccpdf->getPdf($data);
$this->load->helper('download');
$filename = 'Daily_delivery_sheet.pdf';
force_download($filename, $pdf);
exit;

排查与解决方案 #

• 优先排查输出缓冲区污染问题：这是该故障最高发的诱因。如果在调用force_download()前，代码已经输出了任意内容（包括PHP文件开头的BOM头、调试打印内容、PHP闭合标签?>后多余的空行/空格、前置抛出的非阻断性报错信息），会导致下载响应头被提前发送，Content-Disposition字段中携带的自定义文件名参数失效，浏览器会自动回退使用默认文件名file.pdf。
  修复方式是在调用force_download()前增加缓冲区清空逻辑，清除所有提前输出的内容：

  $pdf = $mcccpdf->getPdf($data);
  $this->load->helper('download');
  $filename = 'Daily_delivery_sheet.pdf';
  ob_clean(); // 清空前置输出的缓冲区内容
  force_download($filename, $pdf);
  exit;
  

• 检查响应头是否被覆盖：确认当前请求的调用链中，没有前置逻辑提前发送Content-Disposition响应头，也没有后置逻辑在force_download()执行后覆盖下载相关的响应头。可通过headers_list()打印当前已生成的所有响应头，检查自定义文件名是否被异常替换。
• 校验PDF生成返回值：确认$mcccpdf->getPdf($data)返回的是纯PDF二进制字符串，没有在内容头部拼接额外的调试信息、HTML标签、报错文本，这类多余内容会污染响应体，间接导致浏览器无法正确解析响应头中的文件名参数。
• 对比同文件正常逻辑的差异：逐行对比可正常生效的下载功能代码，重点核对两个方法在调用force_download()前的逻辑区别，包括是否存在不同的前置输出、是否触发了不同的钩子/中间件逻辑、是否有额外的header发送操作。

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