PHP 8.2文件下载失败核心在于响应头被破坏、文件不可读、权限异常或环境配置缺失；须查日志、验输出时机、测文件真实状态，而非盲目修改header。
PHP 8.2 文件下载失败，核心问题通常不在“写没写对代码”，而在于响应头被破坏、文件不可读、路径权限异常或环境配置缺失。直接看日志、验证输出时机、检查真实文件状态，比反复改 header 更有效。
确认 Content-Disposition 和 Content-Type 是否真正发出
浏览器是否下载，完全依赖这两个响应头。但它们极易被“看不见的输出”破坏：
- 用浏览器开发者工具（Network → Headers）查看响应中是否有
Content-Disposition: attachment; filename="xxx"和准确的Content-Type（如application/pdf，不是text/plain） - 在
header()前加ob_end_clean();，并紧跟if (headers_sent($file, $line)) { die("Header failed at {$file}:{$line}"); }定位输出源 - 中文文件名必须用
filename*=UTF-8''{rawurlencode($name)}格式，只写filename="中文.pdf"在 Chrome/Firefox 中大概率乱码或失效 - 不要用
application/octet-stream当万能兜底——它可能被企业网关拦截，优先查扩展名映射 MIME 类型（如.xlsx → application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）
检查文件路径、权限与可读性
下载逻辑再正确，如果文件根本打不开，也会静默失败或返回空内容：
- 用
realpath($filepath)确认路径是否解析为绝对路径；file_exists($filepath)和is_readable($filepath)必须同时为true - Web 服务器用户（如
www-data或nginx）必须对文件及其所在目录有读取权限，常见错误是上传后文件属主为root，Web 进程无权读 - 若路径含变量（如
$_GET['file']），务必做白名单校验或路径规范化，防止../../etc/passwd类穿越 - 大文件下载禁用
readfile()；改用fopen()+fread()分块（每次 8192 字节），并配合flush()和ob_flush()
排查 PHP 环境与关键配置
很多 500 或空白响应，根源在底层配置未生效：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php -i | grep "upload_tmp_dir\|allow_url_fopen\|file_uploads"，确认allow_url_fopen = On（远程下载必需）、file_uploads = On（涉及上传后中转下载必需） - 检查
upload_tmp_dir是否存在且 Web 进程可写；若为空，PHP 默认用系统临时目录，但某些容器或安全加固环境会限制访问 - CLI 模式下执行
php -v和php -m | grep -E "(curl|openssl|mbstring)"，确保基础扩展已启用（Composer 或远程下载都依赖它们） - 若用 Nginx + PHP-FPM，确认
fastcgi_pass指向正确的 socket（如unix:/run/php/php8.2-fpm.sock），并检查 PHP-FPM 日志（/var/log/php-fpm/www-error.log）里有无Permission denied或open_basedir restriction
验证是否真走到 PHP 下载逻辑
先排除 Web 服务器层拦截：
- 新建一个极简脚本（如
testdl.php），仅含<?php header('Content-Type: text/plain'); echo 'OK'; ?>，访问看是否正常输出。若也报 500，说明问题在环境（PHP-FPM 挂了、Nginx 配置错、SELinux 限制等） - 查看 Nginx 错误日志（
/var/log/nginx/error.log），搜索upstream timed out、connect() failed或no live upstreams，判断是否 PHP-FPM 未响应 - 用
curl -I http://localhost/testdl.php看 HTTP 状态码。如果是 404，说明请求根本没进 PHP；如果是 502/504，说明 PHP-FPM 不可用；只有 200 才代表真正执行了你的脚本
