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. 部分老舊/非標準解析器可能不支援
?>
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_UNICODE | 5.4+ | 不轉義 Unicode 字符 (中文、Emoji 等) | **必加**,所有輸出給前端/日誌的 JSON |
JSON_UNESCAPED_SLASHES | 5.4+ | 不轉義 / (預設轉 \/) | URL、路徑、正則含斜槓時 |
JSON_HEX_TAG | 5.3+ | < > 轉義 | **嵌入 HTML/JS 時必加** (防 XSS) |
JSON_HEX_APOS | 5.3+ | ' 轉義 | 嵌入 HTML 屬性值時 |
JSON_HEX_QUOT | 5.3+ | " 轉義 | 嵌入 HTML 屬性值時 |
JSON_HEX_AMP | 5.3+ | & 轉義 | 嵌入 HTML/URL 時 |
JSON_NUMERIC_CHECK | 5.3+ | 數值字串轉數字 | **慎用**!可能改變數據語意 (如手機號、ID) |
JSON_PRESERVE_ZERO_FRACTION | 5.6+ | 浮點數保留 .0 (1.0 不變 1) | API 契約要求嚴格數值格式 |
JSON_PRETTY_PRINT | 5.4+ | 美化縮進輸出 | 調試、日誌、配置文件 |
JSON_THROW_ON_ERROR | 7.3+ | 錯誤拋出 Exception 而非返回 false | **現代代碼必加**,配合 try-catch |
原文提供的 preg_replace 回調方案有嚴重缺陷:/e 修飾符 **PHP 7.0 移除**,且正則處理 Unicode 代理對 (Emoji) 不正確。
<?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":"中文測試 😀"}
?>
JSON_UNESCAPED_UNICODE、JSON_THROW_ON_ERROR、json_validate() 等現代功能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;
}
?>
Content-Type: application/json; charset=utf-8、資料庫連接編碼、檔案編碼),而非 JSON 本身<?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、保證跨平台互通。