萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP JSON 編碼不轉義中文/Unicode 字符的完整解決方案 (PHP 5.3~8.3)

問題背景

json_encode() 預設會將非 ASCII 字符 (中文、日文、Emoji 等) 轉義為 \uXXXX 格式:

<?php
$data = ['name' => '張三', 'city' => '北京', 'emoji' => '😀'];
echo json_encode($data);
// 輸出: {"name":"\u5f20\u4e09","city":"\u5317\u4eac","emoji":"\ud83d\ude00"}
// 雖然標準 JSON 解析器都能正確還原,但:
// 1. 人類不可讀,調試/日誌極其痛苦
// 2. 傳輸體積增大 (~1 中文字符 6 bytes vs 3 bytes UTF-8)
// 3. 部分老舊/非標準解析器可能不支援
?>

現代標準解法:PHP 5.4+ 內建常量 JSON_UNESCAPED_UNICODE

<?php
$data = ['name' => '張三', 'city' => '北京', 'emoji' => '😀'];

// PHP 5.4+ 直接支援
echo json_encode($data, JSON_UNESCAPED_UNICODE);
// 輸出: {"name":"張三","city":"北京","emoji":"😀"}

// 常用組合旗標 (PHP 5.4+)
$options = JSON_UNESCAPED_UNICODE 
         | JSON_UNESCAPED_SLASHES   // 不轉義 / (預設會轉 \/)
         | JSON_HEX_TAG             // < > 轉 \u003C \u003E (防 XSS)
         | JSON_HEX_APOS            // ' 轉 \u0027
         | JSON_HEX_QUOT            // " 轉 \u0022
         | JSON_HEX_AMP;            // & 轉 \u0026

echo json_encode($data, $options);
// 輸出: {"name":"張三","city":"北京","emoji":"😀"} (斜槓也不轉義)
?>

常用旗標組合速查表

常量PHP 版本作用推薦場景
JSON_UNESCAPED_UNICODE5.4+不轉義 Unicode 字符 (中文、Emoji 等)**必加**,所有輸出給前端/日誌的 JSON
JSON_UNESCAPED_SLASHES5.4+不轉義 / (預設轉 \/)URL、路徑、正則含斜槓時
JSON_HEX_TAG5.3+< > 轉義**嵌入 HTML/JS 時必加** (防 XSS)
JSON_HEX_APOS5.3+' 轉義嵌入 HTML 屬性值時
JSON_HEX_QUOT5.3+" 轉義嵌入 HTML 屬性值時
JSON_HEX_AMP5.3+& 轉義嵌入 HTML/URL 時
JSON_NUMERIC_CHECK5.3+數值字串轉數字**慎用**!可能改變數據語意 (如手機號、ID)
JSON_PRESERVE_ZERO_FRACTION5.6+浮點數保留 .0 (1.0 不變 1)API 契約要求嚴格數值格式
JSON_PRETTY_PRINT5.4+美化縮進輸出調試、日誌、配置文件
JSON_THROW_ON_ERROR7.3+錯誤拋出 Exception 而非返回 false**現代代碼必加**,配合 try-catch

歷史版本兼容方案:PHP 5.3 及以下 (已 EOL,僅維護舊專案參考)

原文提供的 preg_replace 回調方案有嚴重缺陷:/e 修飾符 **PHP 7.0 移除**,且正則處理 Unicode 代理對 (Emoji) 不正確。

安全兼容方案:手動 UTF-8 字節重組 (無 /e 修飾符)

<?php
/**
 * PHP 5.3 兼容:json_encode 不轉義 Unicode
 * 原理:json_encode 產生 \uXXXX,用 preg_replace_callback 還原 UTF-8 字節
 */
function json_encode_unicode_compat(mixed $value, int $options = 0, int $depth = 512): string
{
    $json = json_encode($value, $options | JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP, $depth);
    
    // 匹配 \uXXXX 或 \uXXXX\uXXXX (代理對)
    return preg_replace_callback(
        '/\\\\u([0-9a-fA-F]{4})/u',
        function ($matches) {
            $codepoint = hexdec($matches[1]);
            // BMP 字符 (U+0000 ~ U+FFFF)
            if ($codepoint < 0x10000) {
                return mb_convert_encoding(pack('H*', $matches[1]), 'UTF-8', 'UCS-2BE');
            }
            // 理論上 json_encode 不會單獨產生代理對,但以防萬一
            return $matches[0]; // 保持原樣
        },
        $json
    );
}

// PHP 5.3 測試
$data = ['msg' => '中文測試 😀'];
echo json_encode_unicode_compat($data);
// 輸出: {"msg":"中文測試 😀"}
?>

更簡單的替代:升級 PHP 或用 polyfill

  • **強烈建議升級至 PHP 8.1+** (積極維護版),獲得原生 JSON_UNESCAPED_UNICODE、JSON_THROW_ON_ERROR、json_validate() 等現代功能
  • 若被迫維護 PHP 5.3,考慮引入 symfony/polyfill-php73 (提供 json_validate 等) 或直接複製上述兼容函數

進階:深度控制與錯誤處理

<?php
// 1. 深度限制 (防止遞歸過深導致棧溢出)
$deepArray = range(1, 1000); // 建立深層陣列...
// json_encode($deepArray, 0, 10); // 第 3 參數 $depth = 10,超過拋出錯誤/返回 false

// 2. PHP 7.3+ 強制拋出異常 (推薦)
try {
    $json = json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
} catch (JsonException $e) {
    // 處理編碼錯誤:資源、循環引用、非 UTF-8 字串等
    error_log("JSON encode failed: " . $e->getMessage());
    $json = '{}';
}

// 3. 循環引用檢測 (PHP 7.3+ 會拋出 JsonException)
// 手動檢測輔助函數
function hasCircularRef(mixed $value, array &$seen = []): bool
{
    if (!is_array($value) && !is_object($value)) return false;
    $id = is_object($value) ? spl_object_id($value) : 'arr_' . spl_object_id($value); // 簡易標識
    if (isset($seen[$id])) return true;
    $seen[$id] = true;
    foreach ($value as $v) {
        if (hasCircularRef($v, $seen)) return true;
    }
    return false;
}
?>

前端接收端注意事項

  • **現代瀏覽器/Node.js/所有標準 JSON.parse() 完美支援 UTF-8 字符**,**無需任何特殊處理**
  • 舊版 IE (≤ IE11) 也支援直接解析 UTF-8 JSON
  • 若前端框架 (Vue/React) 顯示亂碼,**問題在傳輸層編碼** (HTTP Header Content-Type: application/json; charset=utf-8、資料庫連接編碼、檔案編碼),而非 JSON 本身

總結:一行代碼解決 99% 場景

<?php
// 現代 PHP (5.4+) 標準寫法
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_THROW_ON_ERROR);

// 終極推薦常量組合 (定義在常用工具類/配置中)
define('JSON_DEFAULT_FLAGS', 
    JSON_UNESCAPED_UNICODE 
  | JSON_UNESCAPED_SLASHES 
  | JSON_HEX_TAG 
  | JSON_HEX_APOS 
  | JSON_HEX_QUOT 
  | JSON_HEX_AMP 
  | JSON_THROW_ON_ERROR
);

// 全項目統一使用
echo json_encode($data, JSON_DEFAULT_FLAGS);
?>

結語

**PHP 5.4+ 直接用 JSON_UNESCAPED_UNICODE 旗標**,配合 JSON_THROW_ON_ERROR (7.3+) 和安全旗標 (JSON_HEX_TAG 等) 組成標準組合。**拒絕使用正則替換舊方案** (含 /e 修飾符、代理對處理錯誤、效能差)。若維護 PHP 5.3 專案,請使用無 /e 的 preg_replace_callback 兼容函數,**並制定升級計劃**。正確的 JSON 編碼策略,能消除調試痛苦、減少傳輸體積、防範 XSS、保證跨平台互通。

copyright © 萬盛學電腦網 all rights reserved