PHP json_validate 遇到非法 UTF-8 时如何区分格式和编码错误

我在接收第三方 JSON 时最容易误判的一类问题，是把“字符串不是合法 UTF-8”和“JSON 少了一个括号”都记成同一个 false。PHP 8.3 起，json_validate() 已经能先做语法校验，但真正有用的是紧接着读取错误码：JSON_ERROR_UTF8 说明编码有问题，JSON_ERROR_SYNTAX 才是 JSON 文本结构有问题。

官方资料：https://www.php.net/manual/zh/function.json-validate.php

为什么非法 UTF-8 不是普通 JSON 语法错

JSON 的花括号、引号、逗号属于结构；字符串里的字节序列属于编码。两者可能同时出现在一条请求里，但排查入口不同。PHP 手册明确说明，json_validate() 只处理 UTF-8 编码字符串；返回 false 后，可以用 json_last_error() 和 json_last_error_msg() 取得原因。

因此不要看到“解析失败”就先调用字符替换。替换可能让请求暂时通过，却把原始数据损坏；先记录错误码，才知道该修复上游编码还是 JSON 结构。

先把默认严格校验写成可排查代码

我更愿意把布尔结果和错误上下文一起返回。下面的两个载荷只是示例：第一个是结构错误，第二个通过十六进制字节构造非法 UTF-8。代码中的输出是预期示意，重点是错误码不要被省略。

判断规则很简单：拿到 JSON_ERROR_SYNTAX，检查 JSON 的标点和值；拿到 JSON_ERROR_UTF8，检查数据库连接字符集、文件编码、消息队列原始字节和上游响应。json_last_error_msg() 适合日志和开发提示，真正的分支判断仍应使用常量。

JSON_INVALID_UTF8_IGNORE 什么时候能用

手册当前列出的 json_validate() flag 只有 JSON_INVALID_UTF8_IGNORE。它表达的是“忽略非法 UTF-8 字符”，不是“把输入修复成正确编码”。如果字段是可丢弃的展示备注，且业务能接受内容缺失，可以在边界层采用；用户昵称、订单地址、签名原文、审计日志等不可丢失字段不应静默忽略。

这里有一个常见坑：不要把 JSON_INVALID_UTF8_IGNORE 当成通用“容错开关”，也不要把 JSON_THROW_ON_ERROR 传给 json_validate()。后者不是该函数当前接受的 flag，非法 flag 会抛出 ValueError。严格模式更适合接口契约；忽略模式必须配合字段分级、来源记录和后续修复。

进入 json_decode() 前的迁移清单

json_validate() 的价值在于：当你只想知道一段 JSON 是否有效、并不马上使用解码结果时，它比构造数组或对象更省内存。但如果下一行就是 json_decode()，两次解析反而是重复工作；官方文档也特别提醒了这一点。

• 只做健康检查：调用 json_validate()，失败时保存 JSON_ERROR_UTF8 或 JSON_ERROR_SYNTAX。
• 马上要使用数据：直接调用 json_decode()，必要时使用 JSON_THROW_ON_ERROR，避免先校验再解码。
• 兼容 PHP 8.2 及更早版本：用同一套 json_decode() 错误处理策略封装兼容层，不要假设原生存在 json_validate()。

我最终会把错误日志至少拆成来源、错误码、错误信息和载荷摘要四个字段。这样“格式错误”和“编码错误”不会在监控里混成一个数字，修复动作也能回到真正负责的上游系统。

相关问题

json_validate() 返回 false 就一定是 JSON_ERROR_UTF8 吗？

不是。它也可能是语法错误、深度超限等问题，必须读取 json_last_error()，不能只凭返回值猜原因。

调用 json_validate() 后还能直接 json_decode() 吗？

可以，但如果马上要消费解码结果，通常应直接解码，因为 json_decode() 本身会执行校验，先调用两次会重复解析。