PHP接口返回错误需确保Content-Type为application/json; charset=utf-8、HTTP状态码语义准确、JSON编码加JSON_UNESCAPED_UNICODE等标志并清理UTF-8数据，框架如ThinkPHP应统一用return json()而非手动echo，避免头冲突与乱码。
PHP 8.0 接口返回数据错误不是响应内容写错了，而是 HTTP 状态码、Content-Type 头、JSON 编码方式或框架异常接管逻辑出了问题，导致前端解析失败、状态误判或中文乱码，必须从响应头→编码→框架层逐层验证。
确认响应头是否正确设置
打开浏览器 Network 面板，点击出错的接口请求 → 查看 Response Headers → 检查 Content-Type 是否为 application/json; charset=utf-8。若显示 text/html 或缺失 charset=utf-8，前端 fetch() 的 response.json() 会直接抛错。
在接口代码最开头加入：header('Content-Type: application/json; charset=utf-8');，且该行必须在任何 echo、print 或 var_dump 之前执行，否则 header 已发送无法修改。
如果用了 ThinkPHP 8.0，不要手动 echo JSON 字符串，应统一用 return json(['code'=>0, 'data'=>$data]);，它会自动设 header 和状态码；手动 echo 后再 return 会导致响应头冲突，返回空白或 500。
立即学习“PHP免费学习笔记（深入）”；
检查 JSON 编码是否崩溃
方法一：用 json_encode() 时加安全标志位
替换旧写法 echo json_encode($data); 为：$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE); if ($json === false) { http_response_code(500); echo json_encode(['error' => 'JSON encode failed: ' . json_last_error_msg()]); exit; } echo $json;
方法二：对数据做 UTF-8 强制转码
尤其当 $data 来自数据库或文件读取时，先遍历清理：array_walk_recursive($data, function(&$v) { $v = mb_convert_encoding($v, 'UTF-8', 'auto'); });，再 encode。不处理可能导致中文字段变成 null，而 json_encode() 不报错也不提示。
定位是框架拦截还是 PHP 层失败
第一步：在 public/index.php 顶部插入两行（必须在 require autoload 之前）：
ini_set('display_errors', '1'); error_reporting(E_ALL);
第二步：关闭 Nginx 的 fastcgi_intercept_errors（如启用），否则 500 错误会被 Nginx 拦截成空白页，真实 PHP 错误永远看不到。
第三步：查看 runtime/log/ 下最新 error 日志，重点找含 “PHP Fatal error”、“Uncaught TypeError”或“json_encode” 的行。若日志为空，说明错误发生在框架加载前（如语法错误、扩展未启用）或被 Web 服务器吞掉。
第四步：临时注释所有中间件和路由逻辑，直连一个最小接口：<?php header('Content-Type: application/json'); echo json_encode(['ok'=>true]);，能返回说明环境正常，问题出在业务逻辑中。
ThinkPHP 8.0 特有陷阱排查
方法1：检查自定义异常处理器是否返回 think\Response
在 app/exception/ExceptionHandle.php 的 render() 方法里，必须返回 json([...], 500) 或 response()->json(...) 这类 think\Response 实例。若写成 return ['code'=>500]; 或 echo json_encode(...); exit;，TP8 会触发二次渲染，返回 HTML 页面混入 JSON 响应，前端解析直接失败。
方法2：确认 APP_DEBUG=false 时是否仍走自定义异常
APP_DEBUG=false 时，TP8 默认不显示堆栈，但只要 app_exception 配置正确且 render() 返回合法 Response，错误仍能被捕获。若此时接口突然返回 500 空白页，大概率是 render() 内部抛了新异常（比如调用了未初始化的 $this->view），导致框架 fallback 到默认 500 页面。
