PHP json_decode 返回 null 如何区分解析错误

json_decode() 返回 null 时，不能直接把它当成解析失败。输入是合法 JSON 文本 null 时，PHP 同样会返回 PHP 的 null；只有紧接着检查 json_last_error()，才能确认这次解码有没有错误。

为什么同一个 null 有两种含义

PHP 手册对 json_decode() 的返回约定包含两个容易混淆的情况：JSON 文本中的 true、false、null 会转换为对应的 PHP 值；如果文本无法解码，或者超过了嵌套深度，也会返回 null。因此，单独写 if ($data === null) 只能说明结果是空值，不能说明原因。

先读取错误码，再判断结果是不是合法 null

兼容旧项目时，最稳妥的顺序是保存原始输入，调用一次 json_decode()，随后立刻读取 json_last_error() 和 json_last_error_msg()。后续如果又调用了其他 JSON 函数，排查时可能已经看不到本次解码的错误状态。

这里的关键不是拿字符串和 'null' 做比较，而是先确认错误码为 JSON_ERROR_NONE。例如带外围空白的 " null\n" 仍然是合法 JSON，使用 trim() 只是为了识别日志语义，不应该用原始字符串比较来代替错误检查。

把常见失败原因映射到可行动的检查项

JSON_ERROR_SYNTAX 通常先检查双引号、尾随逗号和截断响应；JSON_ERROR_UTF8 要回到 HTTP 响应或文件读取环节确认编码；JSON_ERROR_DEPTH 则要检查递归数据或是否错误地把 depth 设得过小。日志里至少保留错误码、错误消息、来源接口和请求追踪 ID，不建议直接把完整敏感载荷写入日志。

 $errorCode,
    'json_error_message' => $errorMessage,
    'payload_length' => strlen($payload),
    'request_id' => $requestId,
];

// 只记录长度和请求标识，避免把访问令牌或个人数据写入日志。
error_log(json_encode($diagnostic, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR));
?>

如果业务必须接受空响应，要把“空响应”和“合法 JSON null”定义成不同状态；如果接口契约要求对象或数组，则即使错误码为零，也要继续检查 is_array() 或字段是否存在。解析成功不等于业务结构一定符合预期。

新代码优先用 JSON_THROW_ON_ERROR

在 PHP 7.3 及以上，可以给 json_decode() 传入 JSON_THROW_ON_ERROR。发生语法、深度或 UTF-8 等解码问题时，函数会抛出 JsonException，失败不再和合法的 null 共用一个返回值。对需要兼容旧 PHP 的项目，继续使用错误码分支，并把这条兼容策略写在封装函数中。

getMessage());
    throw new RuntimeException('上游 JSON 无法解析', 0, $exception);
}
?>

常见问题

json_decode('false') 返回的是失败吗？

不是。带引号的 JSON 文本 false 是合法值，会得到 PHP 的布尔值 false；仍应检查错误码，而不是用真假判断代替解析状态。

json_last_error() 应该什么时候调用？

紧跟在对应的 json_decode() 后调用。它反映最近一次未使用 JSON_THROW_ON_ERROR 的 JSON 操作，后续调用可能改变你要诊断的状态。

只判断 json_last_error_msg() 是否为 “No error” 可以吗？

可以显示给人看，但程序分支应比较 json_last_error() === JSON_ERROR_NONE，用常量表达逻辑更稳定，也便于针对深度和编码错误分别处理。

合法 null 也要报错怎么办？

在错误码为零后，再按接口契约检查结果类型。例如接口必须返回对象，就用 is_array() 或对象判断拒绝空值，并记录“结构不符合契约”，不要把它误写成 JSON 语法错误。