前端傳遞、URL 編碼、HTML 實體、JavaScript escape() 輸出等場景,會產生多種 Unicode 表示格式:%uXXXX、XXXX;、NNNN;。本文提供一個通用解碼函式,一次處理所有格式,並深入解析 UCS-2LE/BE 跨平台陷阱。
<?php
/**
* 將多種 Unicode 表示格式解碼為 UTF-8 字串
* 支援:%uXXXX, XXXX;, NNNN;, 以及純文字混合
* @param string $str 輸入字串
* @return string UTF-8 字串
*/
function unicode_to_utf8(string $str): string
{
// 先處理 URL 編碼(%uXXXX 通常來自 escape() 後再 urlencode)
$str = rawurldecode($str);
// 正則匹配三種格式
$pattern = '/%u([0-9A-Fa-f]{4})|([0-9A-Fa-f]+);|(\d+);/';
return preg_replace_callback($pattern, function ($matches) {
// $matches[1] = %uXXXX, [2] = XXXX;, [3] = NNNN;
if (!empty($matches[1])) {
$hex = $matches[1];
} elseif (!empty($matches[2])) {
$hex = $matches[2];
} else {
$dec = (int)$matches[3];
return mb_chr($dec, 'UTF-8');
}
$codepoint = hexdec($hex);
// 使用 UTF-16BE 封裝後轉 UTF-8,避免 UCS-2LE/BE 端序問題
return iconv('UTF-16BE', 'UTF-8', pack('n', $codepoint));
}, $str);
}
// 測試
$tests = [
'%u7D2B%u661F%u85CD', // JavaScript escape() 輸出
'紫星藍', // HTML 十六進制實體
'繋昣藍', // HTML 十進制實體
'紫星藍', // 純 UTF-8(應保持不變)
'Hello %u4E16界世', // 混合格式
];
foreach ($tests as $t) {
echo "Input: $t\n";
echo "Output: " . unicode_to_utf8($t) . "\n\n";
}
| 平台 | 預設 UCS-2 端序 | iconv 識別名稱 |
|---|---|---|
| Windows | Little-Endian (LE) | UCS-2LE |
| Linux/macOS | Big-Endian (BE) | UCS-2BE |
直接指定 UCS-2 會依平台預設端序導致跨平台不一致!
pack('n', $codepoint)(n = unsigned short, big-endian)UTF-16BE 為來源編碼轉換:iconv('UTF-16BE', 'UTF-8', $packed)<?php
// JS escape() → PHP 解碼
$jsEscaped = '%u7D2B%u661F%u85CD'; // "紫星藍"
echo unicode_to_utf8($jsEscaped); // 紫星藍
// PHP 編碼 → JS unescape()
function php_escape(string $str): string
{
$result = '';
$len = mb_strlen($str, 'UTF-8');
for ($i = 0; $i < $len; $i++) {
$char = mb_substr($str, $i, 1, 'UTF-8');
$cp = mb_ord($char, 'UTF-8');
if ($cp < 0x80) {
$result .= $char;
} else {
$result .= '%u' . strtoupper(dechex($cp));
}
}
return $result;
}
$phpEncoded = php_escape('測試中文'); // %u6E2C%u8A66%u4E2D%u6587
// JS: unescape('%u6E2C%u8A66%u4E2D%u6587') → "測試中文"
| 現象 | 原因 | 解決 |
|---|---|---|
| Linux 下 iconv('UCS-2', 'UTF-8', ...) 亂碼 | Linux 預設 UCS-2BE,Windows 為 UCS-2LE | 明確指定 UTF-16BE + pack('n') |
| 輸出字串前面出現 (BOM) | iconv 輸出含 BOM (FEFF/FFFE) | 解碼後 ltrim($str, "\xEF\xBB\xBF") 移除 |
| 增補平面字元(Emoji)解碼錯誤 | UCS-2 僅支援 BMP (U+0000~U+FFFF) | 改用 UTF-16BE + pack('N') 處理 4 位元組,或直接用 mb_chr |
| 雙重編碼(%25uXXXX) | 前端已 urlencode,後端又 rawurldecode | 確認只解碼一次,或檢查前端傳輸流程 |
input('data'));
Unicode 格式多樣、跨平台端序易踩坑。掌握 統一打包為 UTF-16BE → iconv 轉 UTF-8 的核心模式,並善用 mb_chr/mb_ord(PHP 7.2+)處理增補平面,即能建立健壯的通用解碼器。記得:永遠明確指定編碼名稱,不要依賴平台預設的 UCS-2。