PHP JSON 接口中文乱码排查：从响应头到编码路径的完整修复

PHP 接口本地看着没问题，一放到浏览器或前端请求里就出现中文乱码、空白响应，甚至 JSON 解析失败，这是很多后台接口调试时会遇到的老问题。本文不先背概念，而是跟着一次排查过程走：先看现场，再猜原因，接着用小片段验证，最后把响应头、编码和返回出口统一起来。

适合读者：正在写 PHP 接口、管理后台 API、AJAX 数据返回，或者遇到中文字段显示异常的开发者。示例使用原生 PHP 思路，框架项目也可以把同样的检查点迁移到控制器、中间件或统一响应类里。

问题现场：接口有数据但页面看到乱码

我们先看现象。接口查询出来的数组里明明有中文，例如商品名、用户名、备注字段都正常，但浏览器里直接访问接口时，返回内容像被打乱了一样；前端请求后再解析，有时还能看到 JSON 解析报错。

这种问题容易被误判成数据库乱码。可是如果在 PHP 里临时打印数组，中文字段又是正常的，那数据库和查询语句就未必是第一嫌疑。我们先把问题拆成三段：数据进入 PHP 时是不是 UTF-8，PHP 输出前有没有多余内容，HTTP 响应头有没有声明 JSON 和字符集。

初步判断：先把响应头和输出顺序看清楚

第一个猜测是响应头缺失。JSON 接口最好明确告诉客户端：这是 JSON，并且字符集是 UTF-8。很多页面能“凑合显示”，是浏览器自己猜编码；接口一旦被前端、网关或移动端消费，猜编码就不可靠了。

 0,
    'message' => '成功',
    'data' => [
        'title' => '中文商品',
        'remark' => '库存正常'
    ],
];

header('Content-Type: application/json; charset=utf-8');
echo json_encode($data, JSON_UNESCAPED_UNICODE);

这段代码只做两件事：先声明响应类型和字符集，再把数组转成 JSON 字符串。注意响应头要在任何输出之前发送。哪怕前面只有一个空格、BOM 字符、调试输出，都可能让响应头设置失败，后面再怎么改 JSON 参数也不稳定。

动手验证：用最小接口复现问题

接着验证这个猜测。我们不要直接在复杂业务接口里改来改去，而是新建一个最小测试接口，只保留中文数组、响应头和 JSON 返回。这样可以把数据库、权限、模板渲染、框架拦截器先排除掉。

 true,
    'user' => [
        'name' => $name,
        'city' => $city,
    ],
];

echo json_encode($result, JSON_UNESCAPED_UNICODE);

如果这个最小接口返回正常，而业务接口仍然乱码，问题多半在业务接口的输出链路里：比如某个公共文件提前输出、某段调试内容混进响应、框架异常页被拼到了 JSON 前面。如果最小接口也乱码，再继续检查 PHP 文件编码、Web 服务器默认字符集和客户端查看方式。

定位原因：编码、额外输出和返回出口混在一起

现在可以定位到更具体的原因。PHP JSON 乱码通常不是一个点坏了，而是几个小问题叠在一起：

• PHP 文件不是 UTF-8 编码，字符串字面量进入程序时已经异常。
• 响应头没有声明 application/json; charset=utf-8，客户端只能猜。
• 接口返回前已经有调试文本、HTML 片段或空白字符输出。
• 数据源本身混入了非 UTF-8 字节，导致 JSON 转换失败或字段变成空。

判断时可以先看返回内容的第一行。如果 JSON 前面出现 HTML、notice 提示、空白行，就先清理输出顺序；如果返回体结构完整但中文显示异常，再看响应头和源数据编码；如果整个返回为空，优先检查 JSON 转换后的结果和 PHP 错误日志。

修复方案：统一响应头、编码和返回出口

修复思路不要散。建议把接口返回收口到一个函数里：统一响应头、统一 JSON 参数、统一错误兜底。业务代码只负责准备数组，不到处直接输出字符串。

 500,
            'message' => 'JSON 转换失败',
        ], JSON_UNESCAPED_UNICODE);
    }

    echo $json;
}

json_response([
    'code' => 0,
    'message' => '成功',
    'data' => [
        'title' => '中文商品',
        'status' => '已上架',
    ],
]);

这一步的关键不是某个参数多神奇，而是把返回路径固定下来。JSON_UNESCAPED_UNICODE 让中文直接可读，JSON_INVALID_UTF8_SUBSTITUTE 可以在遇到异常字节时用替代字符兜底，避免整个返回直接失败。正式项目里还应把错误记录到日志，方便追到具体字段。

验证结果：浏览器、curl 和前端都要过一遍

最后确认修复是否真的生效，不只看浏览器页面。建议按下面三步检查：

1. 浏览器直接访问接口，确认返回体是完整 JSON，中文可读，没有 HTML 或多余空白。
2. 用 curl 查看响应头，确认存在 Content-Type: application/json; charset=utf-8。
3. 让前端按 JSON 解析接口，确认字段值、状态码和错误分支都符合预期。

curl -i http://localhost/test-json.php

如果 curl 里响应头正确，但前端仍然异常，就继续看前端是否手动按文本处理、代理层是否改了响应头、接口是否被缓存成了旧结果。排查要顺着链路走：PHP 输出正确，只说明后端这一段过关，不能代表代理和浏览器处理也一定没有问题。

常见误区与总结

常见误区有三个。第一，只改数据库连接字符集，却不看 HTTP 响应头；第二，在接口里混用 HTML 输出和 JSON 输出；第三，把 JSON 转换失败当成“没有数据”，结果真正的异常字段被忽略了。

这次排查我们从现象出发，先复现，再缩小范围，最后把响应头、编码和返回出口收口。以后遇到 PHP JSON 中文乱码或空白响应，可以按这个顺序检查：先确认数据本身，再确认输出前没有杂质，再确认响应头，最后检查 JSON 转换结果。只要链路每一段都能被验证，问题就不会变成玄学。