ThinkPHP中response()->download()需传绝对路径并手动指定Content-Type，中文文件名用rawurlencode()编码；json()自动设JSON头，raw()需手动contentType()；自定义后缀需Nginx与PHP双侧配置MIME；非控制器中response()必须显式send()。
response()->download() 传绝对路径并手动指定 Content-Type
ThinkPHP 的 response()->download() 默认会根据文件扩展名推断 MIME 类型，但经常不准——比如 .xlsx 可能被识别成 text/plain，导致浏览器直接渲染乱码而非下载。必须显式传入正确的 Content-Type 头。
关键点：
- 路径必须是服务器上的真实绝对路径，不能是 URL 或相对路径（
response()->download('https://...')直接报错） - 文件名含中文时，要用
rawurlencode()编码，否则 Chrome 可能截断或解析失败 - 常见 Office 文件类型要写全：
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet（xlsx）、application/vnd.openxmlformats-officedocument.wordprocessingml.document（docx） - 不要依赖
mime_content_type()或扩展名自动推测，它在部分系统上不可靠，且不支持自定义映射
示例：
return response()->download(
'/var/www/app/public/files/report.xlsx',
rawurlencode('月度报表.xlsx'),
['Content-Type' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet']
);
json() 和 raw() 的 Content-Type 行为差异
response()->json() 自动设好 Content-Type: application/json; charset=utf-8，安全省心；但 response()->raw() 默认用的是 text/html，哪怕你输出的是 JSON 字符串，前端调用 fetch().json() 也会抛 Unexpected token 错误。
立即学习“PHP免费学习笔记（深入）”；
所以：
- 返回结构化数据，优先用
json($data)，别手拼raw(json_encode(...)) - 真要用
raw()（比如输出 SVG 或自定义文本流），必须手动加contentType()，且带上charset -
json_encode($data, JSON_UNESCAPED_UNICODE)在 ThinkPHP 内置json()中已默认启用，不用额外加
错误写法：
response()->raw(json_encode(['ok' => true])) // Content-Type 是 text/html ❌
正确写法：
response()
->raw(json_encode(['ok' => true]))
->contentType('application/json; charset=utf-8') ✅
自定义响应类型需提前注册 MIME 映射
ThinkPHP 不会自动识别你新增的文件后缀（如 .api、.wasm、.webp），如果走 response()->download() 或静态资源路由，Nginx 层可能 fallback 到 default_type，导致浏览器解析异常。
解决方式分两层：
- Nginx 侧：在
http块或对应server块里补全types块，例如：application/wasm wasm;、image/webp webp; - PHP 侧：若需在代码中动态判断某路径的 MIME（比如做代理响应），不能只靠
pathinfo($ext)，应结合finfo_file()探测真实类型，尤其对用户上传或临时生成的文件 - ThinkPHP 自身不维护 MIME 映射表，它依赖 PHP 环境和 Web 服务器——也就是说，
response()->download()能否正确设头，最终取决于 Nginx/Apache 是否把后缀映射到了对的类型
中间件或钩子里用 response() 必须显式 send()
在控制器方法里 return response()->xxx 框架会自动发送；但在中间件、事件监听器、命令行任务等非控制器上下文中，response() 构建完对象就结束了，不会自动输出，结果就是 HTTP 响应体为空，curl 看到状态码 200 但 body 是空的。
务必手动触发：
- 加
->send()，例如：response()->json(['code' => 0])->send() - 调用后不能再有
echo、var_dump()或其他输出，否则报headers already sent - 注意
send()是一次性操作，重复调用无效果，也不会报错，容易误以为“没生效”而反复调试
这个细节在 API 网关类中间件里最容易踩坑——你以为返回了 JSON，其实什么都没发出去。
