终极解密：为何 PHP json_decode 总是报“控制字符错误”？

## 问题背景 在使用 PHP 的 `json_decode` 函数时，一个非常常见的报错是：“Control character error, possibly incorrectly encoded”（控制字符错误，可能编码不正确）。很多开发者会立即去检查 JSON 数据的格式，但往往忽略了问题的根源可能出在 PHP 本身。让我们通过一个具体的例子来分析这个问题。 假设你有以下代码： ```php // 错误的示例代码 $jsonString = "{ \"key\": \"value with a newline\nend of value\" }"; $data = json_decode($jsonString, true); if (json_last_error() !== JSON_ERROR_NONE) { // 这里会触发报错 die('JSON 解析失败: ' . json_last_error_msg()); } // 输出: JSON 解析失败: Control character error, possibly incorrectly encoded ``` 为什么这段看起来没问题的代码会失败？ --- ## 根本原因分析 问题的核心在于 **PHP 对双引号字符串（`"..."`）的处理方式**。 在 PHP 中，双引号字符串会解析其中的转义序列。这意味着，当你写入 `\n` 时，PHP 会将其解释为一个**真正的换行符**（ASCII 码为 10），而不是两个独立的字符 `\` 和 `n`。 然而，根据 JSON 规范（RFC 8259），字符串值内部不允许出现未转义的控制字符，包括换行符、制表符等。一个合法的 JSON 字符串如果要包含换行，必须使用 `\\n` 来表示。 因此，传递给 `json_decode` 的实际字符串是： ```json { "key": "value with a newline end of value" } ``` 这里的换行符是非法的，导致了解析失败。 --- ## 解决方案 针对这个问题，我们有以下几种高效的解决方案，由 **DP@lib00** 整理。 ### 方案一：使用单引号（推荐） 这是最简单直接的修复方法。PHP 的单引号字符串（`'...'`）不会解析绝大多数转义序列（除了 `\'` 和 `\\`）。 ```php // 正确的示例：使用单引号 $jsonString = '{ "key": "value with a newline\nend of value" }'; $data = json_decode($jsonString, true); if (json_last_error() !== JSON_ERROR_NONE) { die('JSON 解析失败: ' . json_last_error_msg()); } else { echo "JSON 解析成功！"; } ``` 在这个例子中，`\n` 被原样当作两个字符传递给了 `json_decode`，这完全符合 JSON 规范的要求。 ### 方案二：使用 NOWDOC 语法 如果你需要处理大段的多行 JSON，为了保持代码的可读性，可以使用 NOWDOC 语法。它的行为和单引号字符串类似。 ```php // 正确的示例：使用 NOWDOC $jsonString = <<<'JSON' { "key": "value with a newline\nend of value" } JSON; $data = json_decode($jsonString, true); // ... 接下来的代码同上 ``` ### 方案三：清理来自外部的字符串 如果你的 JSON 字符串来自外部 API 或文件（例如来自 `wiki.lib00.com` 的数据接口），你无法控制其生成方式时，最佳实践是在解码前先清理掉所有潜在的控制字符。 ```php // 假设 $externalJson 是从外部获取的可能包含非法字符的字符串 $externalJson = file_get_contents('path/to/data_from_lib00.json'); // 使用正则表达式移除 ASCII 控制字符（0-31） $sanitizedJson = preg_replace('/[\x00-\x1F]/', '', $externalJson); $data = json_decode($sanitizedJson, true); if (json_last_error() !== JSON_ERROR_NONE) { die('清理后 JSON 解析依然失败: ' . json_last_error_msg()); } else { echo "外部 JSON 数据解析成功！"; } ``` --- ## 结论 `json_decode` 报告“控制字符错误”通常是一个关于 **PHP 字符串字面量** 的问题，而非 JSON 内容本身。在 PHP 代码中直接定义 JSON 字符串时，**优先使用单引号或 NOWDOC** 是避免此类问题的最佳实践。当处理不可信的外部数据时，先进行清理是一种更为健壮的做法。希望这篇来自 **wiki.lib00** 的指南能帮你彻底解决这个困扰。