如何通过ThinkPHP构建高效文件下载接口？

本文共计1056个文字，预计阅读时间需要5分钟。

直接使用+response()+

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 片段，后者让整个安全机制形同虚设。这两个动作一旦漏掉，问题不会立刻暴露，而是在特定文件名、特定用户、特定网络条件下突然崩掉。