ThinkPHP 文件下载需正确设置响应头、关闭输出缓冲并规范处理中文文件名，否则会导致0字节、乱码或二进制内容直接输出；推荐用 response()->download() 配合 realpath 校验路径、RFC5987 编码文件名及流式输出大文件。
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 字符没有统一约定。
- 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 或超时。
立即学习“PHP免费学习笔记（深入）”；
- 关键动作：在
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; } - 注意：此时不能有任何 echo/print/debug 输出在之前执行，否则 header 已发送会报“headers already sent”
真正麻烦的从来不是“怎么下”，而是“怎么不下错”——路径校验漏了导致任意文件读取，中文名没按 RFC 编码导致 Safari 下不了，大文件忘了关 buffer 把 PHP 进程干崩。这些点不在文档首页，但在上线前必踩。
