ThinkPHP文件下载功能实现-ThinkPHP-PHP中文网

thinkphp 文件下载需正确设置响应头、关闭输出缓冲并规范处理中文文件名，否则会导致0字节、乱码或二进制内容直接输出；推荐用 response()->download() 配合 realpath 校验路径、rfc5987 编码文件名及流式输出大文件。

thinkphp文件下载功能实现

ThinkPHP 的文件下载不是调用一个函数就完事的，核心在于正确设置响应头、避免缓冲干扰、处理中文文件名兼容性——否则会下出 0 字节文件、乱码或直接输出二进制内容到浏览器页面。

用 `response()->download()` 是最简方式，但要注意路径和 MIME 类型

ThinkPHP 6+ 内置的 response()->download() 能自动处理大部分逻辑，但前提是传入的文件路径必须是服务器上的真实绝对路径（不是 URL），且文件可读。

错误写法：response()->download('https://example.com/file.pdf') —— 这会报错，它不支持远程 URL
正确写法：response()->download('/var/www/app/public/files/report.pdf')
如果 MIME 类型识别不准（比如 .xlsx 被当成 text/plain），可手动指定：response()->download($path, '报表.xlsx', ['Content-Type' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'])
注意：路径不要拼接用户输入，防止路径遍历，建议用 realpath() 校验后限定在白名单目录内

中文文件名在 Chrome/Firefox/Safari 表现不一，得按 RFC5987 规范编码

直接传中文名如 '订单-2024.xlsx'，Chrome 可能显示为乱码或下成 filename.bin，Safari 更可能拒载。根本原因是 HTTP 响应头 Content-Disposition 对非 ASCII 字符没有统一约定。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

ThinkPHP 默认用 rawurlencode() 处理，但不够兼容；推荐手动构造 RFC5987 格式：filename*=UTF-8''%E8%AE%A2%E5%8D%95-2024.xlsx
实操建议：封装一个辅助函数生成合规 header 值，例如：
```
function encodeFilename(string $filename): string{
    return 'filename*=UTF-8\'\'' . rawurlencode($filename);
}
```
然后传给 download() 的第三个参数：['Content-Disposition' => 'attachment; ' . encodeFilename('订单-2024.xlsx')]
别用 iconv('UTF-8', 'GB2312', $name)，旧 IE 已淘汰，且 GB2312 不覆盖所有汉字

大文件下载卡死或内存溢出？必须绕过框架默认输出缓冲

ThinkPHP 默认开启输出缓冲（ob_start()），对小文件无感，但下载几百 MB 文件时，整个文件会被先读进内存再吐出，极易触发 Allowed memory size exhausted 或超时。

关键动作：在 download() 前清空并关闭所有输出缓冲：ob_end_clean();，再调用 flush() 和 gc_disable()（可选）

更稳妥做法：不用 response()->download()，改用原生 PHP 流式输出：

if (file_exists($path) && is_readable($path)) {
    header('Content-Description: File Transfer');
    header('Content-Type: application/octet-stream');
    header('Content-Disposition: attachment; ' . encodeFilename(basename($path)));
    header('Expires: 0');
    header('Cache-Control: must-revalidate');
    header('Pragma: public');
    header('Content-Length: ' . filesize($path));
    readfile($path); // 不加载全量到内存
    exit;
}