必须写return json($data)，因为json()仅构造think\Response对象而不自动响应，不return则对象丢失，框架无法处理；它自动设Content-Type、不转义中文、兼容调试模式并支持链式header设置。
ThinkPHP控制器必须写 return json($data)，不是因为“语法要求”，而是因为 json() 本身不输出、不响应，它只构造一个 think\Response 对象；不 return，这个对象就丢了，框架根本不会处理它。
为什么只调用 json() 没用？
json($data) 是个工厂方法，返回值是 think\Response 实例，不是字符串也不是 void。ThinkPHP 的控制器执行流程依赖“返回值”来决定如何响应——框架在方法执行完后检查你 return 了什么，再交给响应系统统一 send。
- 写了
json($data);但没return→ 方法实际返回null，框架当成空响应或尝试渲染模板，结果常是空白页或 500 - 写了
echo json_encode($data); exit;→ 绕过框架响应生命周期，Content-Type不设、中文被转义、调试模式下 Trace 丢失、中间件不生效 - 写了
return $data;（数组）→ 框架默认当视图变量，可能触发模板渲染，输出 HTML 或报错
return json() 会自动做哪些事？
它不是简单封装 json_encode()，而是一整套响应保障：
- 自动设置
Content-Type: application/json; charset=utf-8，无需手动header() - 默认启用
JSON_UNESCAPED_UNICODE，中文不转\uXXXX - 兼容调试模式：Trace 信息仍可输出，不影响 JSON 结构
- 支持链式设置头信息：
return json($data)->header(['X-Api-Version' => 'v1']); - 能正确处理资源句柄、
DateTime等特殊类型（内部调用Json::encode()）
常见踩坑点：明明写了 return json() 还出错
现象包括：响应头仍是 text/html、返回内容带 HTML 标签、浏览器下载文件、控制台报 Unexpected token <。
立即学习“PHP免费学习笔记（深入）”；
- 路由匹配到了带模板渲染的中间件（比如
ViewInit），需在路由分组里显式禁用：->withoutMiddleware(\think\middleware\ViewInit::class) - 控制器继承了自定义基类，且该基类里有
$this->fetch()或其他视图调用，哪怕没执行也会污染响应通道 - 文件开头有 BOM（尤其是 config/ 或 route/ 目录下的 PHP 文件），导致响应体前多出
\xEF\xBB\xBF字节 - 前置代码抛了 Warning（如访问未定义数组键），PHP 输出了错误文本，JSON 被截断
- 用了
$this->request->input()（TP6/8 已废弃），结果取不到数据，$data为空数组，但你以为是正常响应
最隐蔽的问题往往不在 json() 本身，而在它之前有没有“安静地执行完”——任何输出、警告、中间件拦截、BOM 字节，都会让这个看似简单的 return json($data) 失效。
