文件下载接口打不开通常因请求未抵达控制器，需重点排查三方面：一是前端路由fallback误吞/api/download路径，应排除api/*；二是CORS预检未通过，需确保think-cors中间件靠前注册且allow_methods含GET、OPTIONS；三是响应被echo或框架自动包装污染，应使用response()->download()并清除输出缓冲。
文件下载接口打不开，通常不是代码写错了，而是请求根本没进到控制器——多数情况卡在路由、响应头或框架拦截环节。重点排查三块：接口是否被前端路由吞掉、是否被CORS预检拦住、是否因输出干扰导致流式响应失败。
检查路由是否被前端 fallback 规则覆盖
前后端分离项目中，常见错误是把所有非 API 请求都 fallback 到 index.html，但没排除 /api/ 路径，导致 /api/download 被前端接管，后端控制器压根没执行。
- 确认 route/app.php 或 config/route.php 中的 fallback 规则加了路径排除，例如：
Route::rule('[:path]', 'index/index')->ext('html')->except(['api/*']); - 避免使用宽泛正则如
@^/:path$，它会匹配 /api/download 并重定向到前端，造成 404 或空白响应 - 用
php think route:list查看实际注册的路由，确认GET api/download是否存在且指向正确控制器方法
确认 OPTIONS 预检是否通过，避免跨域中断下载
浏览器发起下载请求（尤其是带 Authorization 或 Cookie 的）时，仍会先发 OPTIONS 预检。若未响应 204 或返回必要头，整个请求会被静默终止。
- 确保已安装并启用
think-cors扩展，且中间件在 app/middleware.php 中靠前注册 - config/cors.php 中必须包含
'allow_methods' => ['GET', 'POST', 'OPTIONS']，否则 GET 下载请求会被拒绝 - 如果下载接口需登录态（如 JWT），前端 fetch 要显式设
mode: 'cors'和headers: { Authorization: 'Bearer xxx' }；若用 withCredentials，则 origin 不能为 *
验证响应是否被框架默认行为污染
ThinkPHP 默认对控制器返回做类型判断，若你用 return Response::stream(...)，但前面有 echo/print 或日志输出，会导致 header 已发送，流式响应失败。
立即学习“PHP免费学习笔记（深入）”；
- 下载方法内不要有任何
dump()、echo、var_dump()或未捕获的异常输出 - 确保
default_return_type在 config/app.php 中设为'html'或留空，避免框架自动包装 JSON 干扰二进制流 - 推荐用标准流式写法：
return response()->download($filePath, $filename);，它内部已处理 flush、header 和 Content-Length - 若手动 stream，务必在函数开头加
ob_end_clean();清除可能存在的输出缓冲
绕过伪静态直接测试入口
快速定位是 Web 服务器问题还是框架逻辑问题：
- 访问
http://your-domain.com/public/index.php/api/download（不走重写），能打开 → 说明是 Nginx/Apache 重写规则漏配/api/路径 - 访问该地址仍失败 → 检查控制器方法是否抛出异常、文件路径是否存在、权限是否可读
- Nginx 用户重点核对
location ~ ^/api/块是否独立配置，避免被location /的 try_files 规则覆盖
