PHP json_encode 中文編碼問題完整解析與解決方案

前言

json_encode() 是 PHP 處理 JSON 的核心函式，但許多開發者在處理中文時會遇到輸出 \uXXXX Unicode 轉義序列，或直接變成 null 的困擾。本文深入剖析根本原因，並提供徹底解決方案。

兩種常見症狀

情況一：輸出 Unicode 轉義序列

{"UserName":"\u00b7\u00f0\u00b5\u00b2\u00c9\u00b1\u00b7\u00f0\u00cc\u00fc"}

這其實是 正常現象。JSON 標準允許以 \uXXXX 表示非 ASCII 字元，前端 JSON.parse() 或 JavaScript 直接解析都會還原成正確中文。Firebug/DevTools 顯示時也會自動解碼。

情況二：中文變成 null

{"UserName":null}

這是 嚴重錯誤。根據 PHP 官方文件，json_encode() 僅支援 UTF-8 編碼輸入。若輸入字串為 GBK、BIG5 等非 UTF-8 編碼，函式會回傳 null 並觸發 JSON_ERROR_UTF8 錯誤。

根本原因追蹤

1. 資料庫/檔案/外部 API 回傳的中文編碼為 GBK（或其他非 UTF-8）
2. PHP 內部字串未轉為 UTF-8 直接送入 json_encode()
3. 導致編碼錯誤，函式回傳 null

解決方案：統一轉為 UTF-8 再編碼

方法一：資料庫連線層指定字元集（推薦）

<?php
// PDO 範例
$pdo = new PDO('mysql:host=localhost;dbname=test;charset=utf8mb4', $user, $pass);

// mysqli 範例
$mysqli->set_charset('utf8mb4');

方法二：PHP 端統一轉碼函式

<?php
/**
 * 遞迴將陣列/物件所有字串值轉為 UTF-8
 * @param mixed $data
 * @return mixed
 */
function toUtf8(mixed $data): mixed
{
    if (is_array($data)) {
        foreach ($data as $key => $value) {
            $data[toUtf8($key)] = toUtf8($value);
        }
        return $data;
    }
    if (is_string($data)) {
        // 偵測編碼並轉換
        $encoding = mb_detect_encoding($data, 'UTF-8, GBK, BIG5, ASCII', true);
        if ($encoding && $encoding !== 'UTF-8') {
            return mb_convert_encoding($data, 'UTF-8', $encoding);
        }
        return $data;
    }
    return $data;
}

// 使用範例
$userData = toUtf8($userObject->toArray());
echo json_encode($userData, JSON_UNESCAPED_UNICODE); // PHP 5.4+ 可直接輸出中文

關鍵參數：JSON_UNESCAPED_UNICODE

PHP 5.4 起支援此旗標，輸出時不轉義 Unicode，直接呈現中文，除錯更直觀：

echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

完整最佳實踐清單

1. 資料庫連線：設定 charset=utf8mb4
2. HTML 頁面：<meta charset="utf-8">
3. PHP 檔案：以 UTF-8 無 BOM 編碼儲存
4. 輸出時：json_encode($data, JSON_UNESCAPED_UNICODE)
5. 接收端：json_decode($json, true) 解碼後若需存入非 UTF-8 資料庫，再 mb_convert_encoding() 轉回原編碼

總結

中文 JSON 問題的核心在於「編碼一致性」。只要確保 資料來源 → PHP 內部 → JSON 輸出 → 前端接收 全鏈路皆為 UTF-8，並善用 JSON_UNESCAPED_UNICODE 旗標，即可徹底解決亂碼與 null 問題。