ThinkPHP 的 json() 方法返回 Response 对象，必须显式 return 才生效；常见错误包括未 return、视图中间件干扰、提前输出导致 header 失败、非法 JSON 输入及状态码设置顺序错误。
json() 方法不返回 JSON 响应？检查 return 和中间件
ThinkPHP 的 json() 不是“输出函数”，它返回一个 think\Response 对象，必须 显式 return 才能触发框架的响应流程。只调用 json($data) 而不加 return，等于构造了一个对象后扔掉，页面会空白或返回原始数组字符串。
常见错误现象包括：Content-Type: text/html、响应体里出现 HTML 标签、浏览器直接下载文件。这些基本都能归因于没 return 或被中间件拦截。
- 控制器方法末尾必须写
return json($data);，不能只写json($data); - 如果启用了视图中间件（如
ViewInit），它会把返回值当模板变量处理，导致 JSON 被套进 HTML 模板里——路由中加->withoutMiddleware(\think\middleware\ViewInit::class)关闭 - TP6.1+ 中某些全局中间件（如日志、Trace）可能在响应前已输出内容，导致 header 已发送，JSON 头设置失败；可临时关闭调试模式验证
Content-Type 是 text/html？确认没手动 echo 或混用 show()
框架的 json() 会自动设置 Content-Type: application/json; charset=utf-8，无需也不该再手动 header()。一旦你在控制器里写了 echo、dump()、show() 或任何输出语句，PHP 的输出缓冲会被提前触发，后续 json() 就无法修改 header，最终 Content-Type 保持默认的 text/html。
- 删除所有
echo、print_r()、var_dump()等调试输出（尤其注意异常捕获块里的echo） - 避免和
success()、error()等视图类方法混用，它们走的是模板渲染通道 - 不要用
header('Content-Type: application/json');+echo json_encode(...)—— 这绕过框架响应机制，极易触发 “headers already sent” 错误
返回的是 null 或乱码？先查输入 JSON 是否合法
json() 方法本身不解析请求体，它只负责输出。但如果你传给它的数据源（比如 input('json_data') 或 $request->json()）本身就是非法 JSON，那输出的就可能是 null、空字符串或含 BOM 的乱码。
用于端到端视频本地化流程的轻量编排器，路由至四个专注子技能——/wjs-transcribing-audio、/wjs-translating-subtitles...
立即学习“PHP免费学习笔记（深入）”；
典型诱因：前端 POST 的 JSON 字符串被截断、数据库字段带 UTF-8 BOM（\xEF\xBB\xBF）、第三方 API 返回了不可见控制字符（如 \x00–\x1F）。
- 每次调用
json_decode()后必须立刻检查：if (is_null($result) && json_last_error() !== JSON_ERROR_NONE) - 用
bin2hex(substr($raw, 0, 16))查前 16 字节，快速识别 BOM（efbbbf）或控制符 - 统一清洗输入比到处修更可靠：在基类或中间件中封装
clean_json_string()，去掉 BOM 和控制符
状态码一直是 200？别用 json() 快捷函数设 code
json($data) 是快捷函数，不支持传入状态码参数。它内部调用的是 response()->json($data)，而后者默认固定返回 200。想改状态码，必须用链式调用：response()->json($data)->code(400)，且 code() 必须在 json() 之后调用——顺序反了会失效，因为 json() 内部已初始化响应。
- 错误写法：
response()->code(400)->json($data)→ 状态码不生效 - 正确写法：
return response()->json(['msg' => '参数错误'])->code(400); - 若需频繁使用非 200 状态码，建议封装一个助手函数，如
json_fail($msg, $code = 400)
json() 本身，而在它上下游的隐性依赖：没 return、中间件抢跑、输入字符串藏了 BOM、状态码调用顺序错了——这些点不逐个排除，光看文档容易绕进死循环。 
