response()->download() 推荐但不能直接使用，因其不校验权限、不防路径遍历、不处理中文名乱码、不支持断点续传且大文件易卡死；需手动加固：白名单路径校验+realpath()检查、rawurlencode()处理中文名、RFC 5987格式Content-Disposition头、ob_end_clean()清缓冲、set_time_limit(0)，大文件优先交由Nginx/Apache传输。
直接用 response()->download() 就能跑通基础下载，但不加校验、不处理中文名、不设超时控制，上线后大概率出问题——比如用户下到空文件、中文名变乱码、大文件卡死、甚至被拖走服务器配置文件。
response()->download() 为什么推荐但不能直接抄代码就用
这个方法封装了大部分响应头逻辑，自动设 Content-Disposition: attachment、Content-Length、Cache-Control 等，省得手写一堆 header()。但它不校验权限、不防路径遍历、不处理 Range 请求，也不管你传进去的路径是不是用户可控的。
- 必须传绝对路径，相对路径（如
./uploads/a.pdf）会报错或下载失败 - 文件名默认取自路径最后一段，若原始文件名含中文，
basename()会截断或乱码，需提前用rawurlencode()处理再传给filename参数 - 不支持断点续传，大文件下载中断后无法恢复，用户只能重来
- 如果文件路径来自
$_GET['file']，没做realpath()+strpos()校验，攻击者可传../../etc/passwd直接读取系统文件
中文文件名下载失败的典型现象和修复方式
Chrome 下载出来是 %E6%8A%A5%E8%A1%A8.pdf 或 ?.pdf，Firefox 报 net::ERR_INVALID_RESPONSE，IE 直接拒绝下载——这不是 ThinkPHP 的锅，是 Content-Disposition 头没按 RFC 5987 写对。
- 不能只写
filename="报表2024.pdf"，浏览器解析失败概率高 - 正确写法是拼两个字段：
attachment; filename="report.pdf"; filename*=UTF-8\'\'%E6%8A%A5%E8%A1%A82024.pdf - ThinkPHP 的
download()支持第 3 个参数传自定义 header 数组，把Content-Disposition替换掉即可 - 示例：
$filename = '销售报表2024.pdf'; $encoded = rawurlencode($filename); return response()->download($filepath, $filename, [ 'Content-Disposition' => 'attachment; filename="' . $filename . '"; filename*=UTF-8\'\'' . $encoded ]);
大文件下载卡死或内存溢出怎么破
ThinkPHP 默认用 readfile() 输出，对几百 MB 以上的文件，PHP 进程可能因内存打满或超时被 kill，Nginx/Apache 也可能中途断连。
立即学习“PHP免费学习笔记（深入）”；
- 先关掉输出缓冲：
ob_end_clean()必须在download()前调用，否则缓存内容混入二进制流 - 设置脚本不限时：
set_time_limit(0)，防止下载中途 30 秒超时 - 真正稳妥的做法是绕过 PHP 流式传输，改用 Web 服务器能力：Nginx 配
X-Accel-Redirect，Apache 配X-Sendfile，让静态文件由 Nginx 直接发，PHP 只做权限判断和 header 控制 - 若必须走 PHP，就别用
download()，改手写流式响应：用fopen()+fread()+echo+flush()分块输出，每次 8192 字节，避免单次加载全量
权限校验和路径安全的硬性检查项
只要接口允许用户传参决定下载哪个文件，就必须做这三件事，缺一不可。
- 文件路径不能拼接用户输入，必须从数据库查映射 ID 对应的真实路径，或限定在白名单目录内（如
/var/www/storage/downloads/） - 拿到路径后立刻调用
realpath($path)，再用strpos()检查是否仍落在白名单根目录下，否则拒掉：$realPath = realpath($path); if (false === $realPath || 0 !== strpos($realPath, '/var/www/storage/downloads/')) { abort(403, 'Access denied'); } - 必须校验当前用户是否有权下载该文件，比如查数据库记录该文件的
user_id是否匹配当前登录态，不能只靠 URL 参数或 session 存在就放行
最易被忽略的是 ob_end_clean() 和 realpath() 校验——前者导致下载文件末尾带 HTML 片段，后者让整个安全机制形同虚设。这两个动作一旦漏掉，问题不会立刻暴露，而是在特定文件名、特定用户、特定网络条件下突然崩掉。
