PHP json_decode 为什么返回 null：JSON_THROW_ON_ERROR、深度限制与输入诊断

接口日志里出现一串看似正常的响应，PHP 代码却把结果判断成了 null。这时别急着给 json_decode() 加默认值：合法 JSON 本身就可能是 null，而语法错误、嵌套深度超限和非法 UTF-8 也可能让调用结果落到同一个表象上。真正稳妥的处理，是把输入、解码选项和错误证据放在同一次调用里核对。

先把 null 分成四种现场

json_decode() 的返回值不能单独承担诊断责任。传入字符串 null 时，返回的确实是 PHP 的 null；传入缺少引号的对象、超过默认深度的嵌套数据或非法 UTF-8 时，也可能得到 null。第一步要把错误码一起读出来：

$value = json_decode($payload, true);
$errorCode = json_last_error();
$errorMessage = json_last_error_msg();

var_dump($value, $errorCode, $errorMessage);

这里有个容易漏掉的边界：json_last_error() 反映的是最近一次 JSON 操作。如果解码后又调用了其他 JSON 函数，排查时看到的错误可能已经不是原始输入造成的。把错误码紧跟在解码语句后读取，证据才可靠。

PHP 8.x 为什么更适合用 JSON_THROW_ON_ERROR

旧代码通常用“返回值加错误码”的组合判断。它能工作，但调用者很容易只写 if ($value === null)，把合法空值和失败混在一起。PHP 7.3 及以后可以传入 JSON_THROW_ON_ERROR，让解码失败直接抛出 JsonException：

$value = json_decode(
    $payload,
    true,
    512,
    JSON_THROW_ON_ERROR
);

调用方可以只捕获 JSON 异常，再把请求 ID、上游名称和错误类别写进结构化日志。不要把完整的用户输入直接写入日志；令牌、手机号和地址等字段应在记录前脱敏。

深度参数不是越大越好

json_decode() 的第三个参数是最大嵌套深度，默认值为 512。遇到 JSON_ERROR_DEPTH 时，可以先确认上游是否意外包了一层层无意义对象，再决定是否调整参数。盲目把深度改成很大，会放宽资源边界，也会让异常输入更难被及时发现。

try {
    $data = json_decode($payload, true, 64, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    $logger->warning('JSON payload rejected', [
        'request_id' => $requestId,
        'error' => $e->getMessage(),
    ]);
}

接口契约允许的深度应该写进测试样例：一份正常样例、一份刚好达到边界的样例，以及一份超过边界的样例。这样升级 PHP 或更换上游 SDK 后，错误不会悄悄退化成一个空值。

把修复动作对准真正的输入问题

语法错误优先检查响应是否被代理截断，编码错误优先核对上游字符集，深度错误优先回看数据结构；只有在确认契约确实需要更深层级时才调整第三个参数。对于客户端可重试的瞬时故障，先重新拉取并校验响应头；对于稳定的格式错误，重试只会放大日志和流量。

相关问题：json_decode 的边界怎么验

合法 JSON 的 null 应该怎么判断？

把返回值和 json_last_error() 一起判断。返回 null 且错误码为 0，表示输入本身是合法的 JSON 空值。

json_last_error_msg() 能代替异常吗？

它适合兼容旧代码和快速诊断；新代码更适合使用 JSON_THROW_ON_ERROR，由异常路径统一处理失败。

出现 JSON_ERROR_DEPTH 是否应该直接把深度调到 4096？

不建议直接放大深度限制。先确认数据结构和接口契约，再用边界样例评估内存、耗时与请求规模。

最小验证闭环

最后保留四条测试：合法的 null、语法错误、非法编码和深度超限。每条都核对返回值或异常类型、日志字段和调用方最终响应。这样下一次看到 null 时，问题会落到一个可操作的分支，而不是继续猜测。