ThinkPHP如何配置安全的文件下载机制【安全】

response()->download() 不能直接使用，因其不校验路径合法性、不防目录遍历、不验证权限、不处理中文名兼容性，传../../etc/passwd可能泄露系统文件；必须用realpath()+白名单前缀校验路径，按RFC5987双格式构造Content-Disposition头，并对大文件启用X-Accel-Redirect或流式传输。

response()->download() 为什么不能直接用

它不校验路径合法性、不防目录遍历、不验证用户权限、不处理中文名兼容性，传个 ../../etc/passwd 就可能把系统文件拖走。默认行为只管“能下”，不管“该不该下”。

常见错误现象包括：下载到 0 字节、浏览器直接渲染 PDF 而非弹框、Safari 拒绝下载、Chrome 显示 %E8%AE%A2%E5%8D%95.pdf 这类编码名。

• 必须传服务器上的真实绝对路径，response()->download('https://...') 或相对路径如 ./uploads/a.pdf 都会失败或引发安全风险
• 文件路径若来自用户输入（如 $_GET['file']），必须先过 realpath() + strpos() 白名单校验，确保结果落在 /var/www/app/storage/ 这类受控目录内
• 不要依赖 basename($path) 提取文件名——原始路径含中文时会截断或乱码，应单独传参并编码

中文文件名怎么避免乱码和拒载

根本问题是 Content-Disposition 头对非 ASCII 字符没有统一约定，各浏览器实现不同。ThinkPHP 默认用 rawurlencode() 包一层，但 Chrome/Firefox/Safari 对 filename= 和 filename*= 的支持程度不一，仅靠前者不够。

必须按 RFC5987 构造双格式头：filename="xxx"; filename*=UTF-8''xxx，否则 Safari 可能直接拒绝响应，Firefox 报 net::ERR_INVALID_RESPONSE。

立即学习“PHP免费学习笔记（深入）”；

• 手动构造 header：用 rawurlencode($filename) 得到编码值，拼成 filename*=UTF-8''%E8%AE%A2%E5%8D%95.pdf
• 第三个参数传数组：['Content-Disposition' => 'attachment; filename="' . $filename . '"; filename*=UTF-8'''. rawurlencode($filename)]
• 别用 iconv('UTF-8', 'GB2312', $name) —— GB2312 不覆盖生僻字，且旧 IE 已淘汰，现代浏览器不认

大文件下载卡死或内存溢出怎么办

ThinkPHP 默认用 readfile() 输出，整个文件先读进 PHP 内存再吐出。几百 MB 文件极易触发 Allowed memory size exhausted 或被 Nginx 的 fastcgi_read_timeout 中断。

关键动作不是优化 PHP，而是绕过它：让 Web 服务器直接发文件，PHP 只做权限判断。

• 下载前必须调用 ob_end_clean()，否则缓冲区残留内容会混入二进制流，导致文件损坏
• 设无限时：set_time_limit(0)，防止脚本超时中断
• 生产环境优先走 Nginx 的 X-Accel-Redirect：PHP 返回 header(X-Accel-Redirect: /protected-files/report.xlsx)，Nginx 查找映射的内部路径并流式传输，完全不经过 PHP 内存
• Apache 对应方案是 X-Sendfile，配置方式不同但逻辑一致

防盗链和权限控制不能只靠 Referer

单纯检查 $_SERVER['HTTP_REFERER'] 毫无意义——curl、Postman、前端 fetch 都可随意伪造或清空它。真要防，得靠服务端签名机制。

典型做法是生成带时效的 token：/download?file=id123&sign=md5(id123+secret+1719342000)&expire=1719342000，服务端验证签名和时间戳是否有效。

• token 必须由后端动态下发，有效期建议 ≤ 300 秒，且不能写死在 JS 或模板里
• 文件必须存放在 public/ 目录之外，比如 runtime/download/ 或 storage/app/private/，杜绝直接 HTTP 访问
• 所有下载请求强制走控制器，校验通过后再调用 response()->download() 或触发 X-Accel-Redirect
• 记录每次下载日志：IP、用户 ID、文件 ID、时间戳，便于审计异常批量请求

最易被忽略的一点：realpath() 校验后，必须用 strpos($realpath, $allowed_dir) === 0 确保路径确实在白名单内——符号链接可能绕过字符串匹配，但无法绕过 realpath() 的物理路径解析。