PHP json_encode 返回 false 怎样处理

我在把数据库查询结果直接交给接口响应时，最容易误判的一类问题就是 json_encode() 返回了 false。它不等于“中文不能编码”，也不等于“数组为空”。PHP 手册明确说明：成功时返回 JSON 字符串，失败时返回 false；真正的原因要结合 JSON 错误状态读取。

官方文档：https://www.php.net/manual/en/function.json-encode.php

处理顺序很简单：不要直接输出 false，先读取 json_last_error_msg()；如果项目使用 PHP 7.3 及以上，优先考虑 JSON_THROW_ON_ERROR，让编码失败变成可捕获的 JsonException。

先把 false 变成可定位的错误

最小排查代码应该紧挨着 json_encode() 调用。json_last_error() 返回错误码，json_last_error_msg() 返回更适合日志的文字。不要在中间再调用其他 JSON 函数，否则排查时容易把注意力放到错误的调用上。

 '示例用户',
    'amount' => 12.5,
];

$json = json_encode($payload, JSON_UNESCAPED_UNICODE);

if ($json === false) {
    // 错误码用于分支，错误消息用于日志和排查。
    $errorCode = json_last_error();
    $errorMessage = json_last_error_msg();
    error_log("JSON encode failed: {$errorCode} {$errorMessage}");
    throw new RuntimeException('响应数据无法编码为 JSON');
}

echo $json;

这里用严格比较 === false，避免把合法的字符串、数字或空 JSON 值与失败混在一起。若日志显示 Malformed UTF-8 characters，优先检查输入字符串的字节来源；若显示递归、资源类型或深度错误，则应回到数据结构本身。

按错误类型看输入，而不是盲目加参数

PHP 的 JSON 常量列出了几类常见失败原因。实际项目里我通常先看错误码，再回溯是哪一个字段进入了编码对象：

递归对象和资源类型尤其不适合靠 JSON_PARTIAL_OUTPUT_ON_ERROR 掩盖。部分输出可能让接口看起来“成功”，但客户端收到的结构已经缺字段，后续更难定位。更稳妥的做法是建立响应 DTO 或数组，只放接口真正需要的字段。

非法 UTF-8：先区分修复数据和替换数据

最常见的误区是看到中文就怀疑中文。PHP 要求待编码的字符串数据使用 UTF-8，真正触发失败的是非法字节序列。若字段来自旧表、外部文件或不明确的转换链路，应先修复数据源，而不是全局忽略字符。

当字段是日志备注、搜索摘要这类“丢掉一个异常字符也可接受”的非核心文本时，可以选择替换策略：

JSON_INVALID_UTF8_IGNORE 会直接丢弃非法字符，风险比替换更难察觉。对姓名、订单号、签名原文等关键字段，我会选择记录错误并修复来源，而不是静默改变内容。

把编码封装成一个小型接口响应函数

如果每个控制器都手写一套判断，项目很快会出现“有的接口返回空字符串、有的接口返回 500、有的接口吞掉错误”的差异。我更倾向于把编码策略集中在一个小函数里：业务代码只负责准备公开字段，函数负责记录异常和返回稳定结果。

getCode(),
            $exception->getMessage()
        ));
        throw new RuntimeException('服务暂时无法生成 JSON 响应', 0, $exception);
    }
}

$response = encodeResponse([
    'ok' => true,
    'data' => ['id' => 1001],
]);

header('Content-Type: application/json; charset=utf-8');
echo $response;

JSON_THROW_ON_ERROR 在 PHP 7.3 引入。若项目仍需兼容更早版本，就保留前面的 === false 与 json_last_error_msg() 方式，不要为了统一写法而忽略部署版本。生产响应也不要把异常消息原样返回给用户，详细原因应留在服务端日志。

我最后会保留的检查清单

这类问题修好后，我会把检查压缩成四个判断：第一，失败分支使用 === false 或捕获 JsonException；第二，日志保存错误码和消息；第三，响应数组不直接暴露递归对象、资源或内部模型；第四，只有明确允许丢失字符时才使用 UTF-8 替换或忽略。

如果问题来自非法 UTF-8，修复数据源通常比换一个编码 flag 更可靠；如果问题来自对象图，建立专用响应结构通常比提高 depth 更安全。对我来说，JSON_THROW_ON_ERROR 适合新项目和可控升级的服务，旧项目则先把错误状态记录完整，再逐步收拢处理策略。

相关问题

为什么 json_encode 中文会返回 false？

合法 UTF-8 的中文本身不会导致失败。先查看 json_last_error_msg()；如果是 UTF-8 错误，检查字符串来源和转换过程。

JSON_INVALID_UTF8_SUBSTITUTE 和 IGNORE 怎么选？

替换会留下替代字符，便于发现数据损坏；忽略会直接丢字符。核心业务字段通常应修复来源，而不是静默选择二者之一。

能不能直接用 JSON_PARTIAL_OUTPUT_ON_ERROR？

只有在业务明确接受部分字段缺失时才考虑。接口、订单和配置数据更适合失败并记录原因，否则客户端可能拿到结构完整但内容不完整的响应。