處理嵌套或複雜結構時，json_last_error 如何幫我們排查JSON 問題？

gitbox 2025-08-28

處理嵌套或複雜結構時，json_last_error 如何幫我們排查JSON 問題？

在PHP 中處理JSON 數據時，我們經常使用json_decode()來將JSON 字符串轉換為PHP 變量。這一過程通常非常直觀，但是在處理嵌套或複雜結構時，常常會遇到解析錯誤，這時候就需要藉助json_last_error()來幫助我們排查問題。

1. json_decode()函數和常見的JSON 問題

json_decode()是PHP 中用於解析JSON 字符串的函數，它能夠將JSON 格式的數據轉換為PHP 的數組或對象。默認情況下， json_decode()會返回一個PHP 對象。如果我們希望返回一個關聯數組，可以傳入第二個參數true 。

例如：

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"name": "John", "age": 30}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);
</span></span>

如果解析JSON 數據時出現問題， json_decode()會返回null ，這時就需要通過json_last_error()函數來確定具體錯誤的原因。

2. 常見的錯誤類型及json_last_error()返回值

PHP 提供了json_last_error()函數來獲取最近一次JSON 操作的錯誤碼。 json_last_error()會返回一個錯誤常量，常見的錯誤常量包括：

JSON_ERROR_NONE ：沒有錯誤，解析成功。
JSON_ERROR_DEPTH ：超過最大堆棧深度（即嵌套過深）。
JSON_ERROR_STATE_MISMATCH ：不合法的JSON 狀態，可能是JSON 被修改過，或者正在處理不合法的JSON 數據。
JSON_ERROR_CTRL_CHAR ：控製字符錯誤，JSON 中出現了非法的控製字符。
JSON_ERROR_SYNTAX ：語法錯誤，JSON 格式不正確。
JSON_ERROR_UTF8 ：UTF-8 編碼錯誤，JSON 字符串中包含無效的UTF-8 字符。

3. 如何使用json_last_error()來排查問題？

處理嵌套或複雜結構的JSON 時，出錯的機率相對較高，因此要能夠快速定位問題所在。通過json_last_error() ，我們可以在出現錯誤時獲得更加詳細的錯誤信息。

例如：

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"name": "John", "address": {"city": "New York", "zip": "10001"}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">json_last_error</span></span><span>() !== JSON_ERROR_NONE) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'JSON 解碼錯誤: '</span></span><span> . </span><span><span class="hljs-title function_ invoke__">json_last_error_msg</span></span><span>();
}
</span></span>

上面的代碼會輸出類似於JSON 解碼錯誤: Syntax error ，幫助我們定位到是語法問題。

錯誤排查案例

假設我們有一個嵌套較深的JSON 數據：

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"user": {"name": "Alice", "details": {"address": {"street": "123 Main St", "city": "Wonderland"}}}}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">json_last_error</span></span><span>() !== JSON_ERROR_NONE) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'錯誤: '</span></span><span> . </span><span><span class="hljs-title function_ invoke__">json_last_error_msg</span></span><span>();
}
</span></span>

這段代碼解析沒有問題，輸出的會是空白，因為JSON 格式是正確的。

然而，如果我們不小心在JSON 中添加了一個多餘的逗號：

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"user": {"name": "Alice", "details": {"address": {"street": "123 Main St", "city": "Wonderland",}}}}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">json_last_error</span></span><span>() !== JSON_ERROR_NONE) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'錯誤: '</span></span><span> . </span><span><span class="hljs-title function_ invoke__">json_last_error_msg</span></span><span>(); </span><span><span class="hljs-comment">// 輸出：錯誤: Syntax error</span></span><span>
}
</span></span>

此時， json_last_error_msg()會返回Syntax error ，因為JSON 語法不正確——多餘的逗號會導致解析失敗。

4. 嵌套結構中的特殊問題

嵌套結構會增加JSON 數據的複雜性，可能會導致一些難以發現的錯誤。例如：

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"user": {"name": "Alice", "address": "Wonderland"}}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">json_last_error</span></span><span>() !== JSON_ERROR_NONE) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'錯誤: '</span></span><span> . </span><span><span class="hljs-title function_ invoke__">json_last_error_msg</span></span><span>(); </span><span><span class="hljs-comment">// 可能輸出 Syntax error</span></span><span>
}
</span></span>

這個例子中，JSON 中的address值應當是一個對象，但實際上是一個字符串。雖然這種錯誤不會引起JSON 解析的直接失敗，但在應用邏輯中處理時，會出現意外的行為。因此，通過json_last_error_msg()可以幫助我們儘早發現這類潛在問題。

5. 深度嵌套問題和JSON_ERROR_DEPTH

當處理非常深層次的嵌套結構時，可能會遇到JSON_ERROR_DEPTH錯誤。此錯誤表明JSON 數據嵌套的層數超過了PHP 配置的最大深度。

 <span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"level1": {"level2": {"level3": {"level4": {"level5": {"level6": {"level7": "end"}}}}}}}}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">json_last_error</span></span><span>() === JSON_ERROR_DEPTH) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'錯誤: JSON 數據嵌套層級過深'</span></span><span>;
}
</span></span>

默認情況下，PHP 對JSON 數據的嵌套層數有限制，可以通過json_decode()的第三個參數depth來調整最大嵌套層數。

 <span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>, </span><span><span class="hljs-literal">true</span></span><span>, </span><span><span class="hljs-number">10</span></span><span>); </span><span><span class="hljs-comment">// 設置最大深度為 10</span></span><span>
</span></span>

6. 如何優化JSON 解析

處理複雜的JSON 結構時，優化解析過程也是非常重要的。常見的優化方法包括：

減小JSON 數據的複雜度：盡量避免過度嵌套，合理設計數據結構。
檢查和驗證輸入數據：在解析JSON 數據之前，確保數據格式正確，避免一些常見的格式錯誤。
增大解析深度：對於確實需要深度嵌套的JSON 數據，可以通過增加最大深度來避免解析錯誤。

7. 結語

在PHP 中， json_last_error()是一個非常有用的工具，它可以幫助我們排查和診斷JSON 解析時的各種問題，特別是在處理嵌套或複雜的JSON 結構時。了解常見的錯誤類型，並學會如何合理使用json_last_error() ，可以幫助開發者更高效地處理JSON 數據並避免一些潛在的錯誤。