ThinkPHP用response()->file()返回本地文件最稳妥，自动设置Content-Type、Content-Length和响应头并流式输出；路径须为绝对物理路径，中文名需urlencode处理，私有文件应改用response()->download()或stream()中转。
ThinkPHP用response()->file()返回本地文件
直接调用 response()->file() 是最稳妥的方式，它会自动设置 Content-Type、Content-Length 和合适的响应头（如 Content-Disposition），并以流式方式输出，不占用内存。别用 readfile() 或 file_get_contents() + echo，那会绕过框架响应生命周期，丢失状态码、中间件拦截和异常处理。
常见错误现象：ERR_CONTENT_LENGTH_MISMATCH（内容长度不一致）、下载后文件损坏、中文文件名乱码、浏览器直接打开 PDF/图片而非下载。
- 路径必须是服务器上的绝对物理路径，不能是相对路径或 URL；例如
public_path('files/report.pdf')，不是./files/report.pdf或https://xxx.com/files/report.pdf - 确保 Web 服务器（Nginx/Apache）允许访问该路径下的文件——如果文件放在
runtime/或storage/目录下，需确认其权限和配置未禁止外部读取（但更推荐放public/下） - 中文文件名必须用
urlencode()处理，并显式传入第二个参数：response()->file($path, ['filename' => urlencode('报表20260901.pdf')])；否则 IE/Edge 可能解析失败 - 若需控制下载行为（如强制下载 vs 在线预览），靠
Content-Disposition：默认是attachment（下载），设为inline可让浏览器尝试内嵌显示：response()->file($path)->header(['Content-Disposition' => 'inline; filename="report.pdf"'])
ThinkPHP返回私有文件（不在public目录下）
当文件存在 runtime/、storage/ 或自定义安全目录时，不能直接暴露路径给前端，必须走控制器中转。这时不能用 response()->file() 简单封装，得手动构造流式响应，避免内存溢出。
关键不是“能不能读”，而是“怎么读得安全又高效”。TP6 没有内置的私有文件下载组件，得自己补一层逻辑。
立即学习“PHP免费学习笔记（深入）”；
- 优先用
response()->download()（TP6.1+ 支持），它底层已做流式处理，且支持断点续传：return response()->download($privatePath, $originalName); - TP6.0 或需要精细控制时，改用
response()->stream()：传入一个回调函数，每次只读取 8192 字节并echo，配合ob_flush()和flush()防止缓冲阻塞 - 务必校验用户权限（如登录态、文件所属关系）在
stream()执行前完成，不能放到回调里——一旦开始输出，HTTP 头已发，无法再跳转或报错 - 不要在回调里调用
$this->error()或throw new Exception()，会导致响应中断且无错误提示；应提前抛出异常，由全局异常处理中间件捕获并返回 JSON 错误
ThinkPHP返回文件时 Content-Type 不对怎么办
response()->file() 会根据扩展名自动推断 Content-Type，但识别库有限（比如不认识 .xlsx 会当成 text/plain），导致浏览器无法正确处理。不能依赖自动识别，尤其对 Office、PDF、字体、WebP 等非标准类型。
根本解法是显式指定 MIME 类型，而不是改服务器配置或试图“修复”框架检测逻辑。
- 查准确 MIME 类型：用
finfo_open(FILEINFO_MIME_TYPE)动态获取（推荐），或硬编码常用类型，例如'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'对应.xlsx - 用
response()->file($path)->contentType($mimeType)覆盖默认值；注意contentType()必须在file()之后链式调用，顺序反了无效 - 避免用
header('Content-Type: ...')手动设——可能被后续框架逻辑覆盖，且易与response()冲突 - 测试时用 curl 查响应头：
curl -I https://yoursite.com/download/test.xlsx，确认Content-Type字段是否符合预期
为什么用 download() 返回文件却没弹出保存框
这不是 ThinkPHP 的问题，而是浏览器策略：当响应来自 AJAX 请求（如 fetch 或 axios），即使服务端返回了正确的 Content-Disposition: attachment，浏览器也不会触发下载，因为 JS 无法主动触发文件保存（安全限制）。
唯一可靠方案是让前端发起**原生 GET 请求**，即用 <a href="/download?id=123" download> 或 window.location.href = '/download?id=123'。
- 如果必须用 AJAX 获取文件元信息（如校验权限、获取文件名），请拆成两步：先
GET /api/download/info?id=123拿到签名和建议文件名，再用<a>标签跳转到带签名的直链 - 不要在
then()里尝试URL.createObjectURL(new Blob([res.data]))—— 对大文件极易卡死，且无法保留原始文件名 - 后端生成的临时直链应有时效性（如 5 分钟过期）和签名验证，防止被恶意刷取
- TP6 中可结合
think\facade\Cache存储一次性的下载 token，避免数据库查询开销
