文件下载失败主因是header设置不当或输出干扰。需确认文件路径正确、使用file_exists检查存在性，合理设置Content-Type、Content-Disposition等响应头，避免BOM和前置输出，大文件应分块读取并调整PHP内存与执行时间限制。
PHP调用文件下载接口失败，通常不是因为网络或权限问题，而是代码逻辑、响应头设置不当导致浏览器无法正确识别和处理文件。最常见的原因出在 header() 函数的使用上。下面从常见问题出发，结合 header 使用教程，帮你快速定位并解决文件下载失败的问题。
一、检查文件路径与是否存在
下载功能的第一步是确保目标文件真实存在且路径正确。
- 使用 file_exists() 验证文件路径是否有效
- 注意相对路径与绝对路径的区别，建议使用 __DIR__ 或 realpath() 获取准确路径
- 确认PHP进程有读取该文件的权限（尤其是Linux服务器）
$filePath = '/var/www/uploads/report.pdf';
if (!file_exists($filePath)) {
die('文件不存在');
}
二、正确使用header函数设置响应头
文件下载的核心在于通过 header() 告诉浏览器这不是普通页面，而是一个需要下载的文件。
- Content-Type：指定MIME类型，常见如 application/pdf、application/octet-stream（通用二进制流）
- Content-Disposition：决定是内联显示还是附件下载，下载必须设为 attachment
- Content-Length：告知文件大小，提升用户体验
- Content-Transfer-Encoding：一般设为 binary
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="downloaded_file.pdf"');
header('Content-Length: ' . filesize($filePath));
header('Content-Transfer-Encoding: binary');
header('Expires: 0');
header('Cache-Control: must-revalidate');
header('Pragma: public');
注意：filename 最好使用英文名，中文需进行 urlencode 处理，否则可能乱码或截断。
立即学习“PHP免费学习笔记（深入）”；
三、避免输出缓冲与额外内容干扰
任何在 readfile() 或 fpassthru() 之前的输出（包括空格、echo、错误信息）都会破坏文件流。
- 确保在发送 header 前没有任何 HTML、echo、var_dump 输出
- 检查PHP文件是否有 BOM 头（特别是UTF-8 with BOM格式），可用编辑器转为“无BOM UTF-8”
- 开启输出控制：ob_clean() 清除缓冲区，flush() 刷新输出
ob_clean(); readfile($filePath); flush(); exit;
四、处理大文件与内存限制
使用 readfile() 直接读取大文件可能导致内存溢出或超时。
- 对于大文件，建议分块读取，使用 fopen() + fread() + fpassthru()
- 调整PHP配置：increase memory_limit 和 max_execution_time
- 生产环境可考虑用X-Sendfile由Web服务器处理下载
基本上就这些。PHP文件下载失败多数是 header 设置不完整或前面有输出。只要路径正确、头信息规范、无多余内容输出，下载功能就能正常工作。调试时可先用小文件测试，再逐步排查权限、编码、缓存等问题。
