PHP 中英混合字串截取完整解決方案：mb_substr、正則、Grapheme Cluster 總整理

核心問題

substr() 按**位元組**截取，中文 UTF-8 佔 3 位元組、Big5 佔 2 位元組，直接使用會導致**亂碼、半個漢字、表情符號截斷**。

方案對照表

方案一：mb_substr() 標準作法 (推薦 95% 場景)

<?php
// 確保內部編碼一致
mb_internal_encoding('UTF-8');
// 或每次呼叫指定
mb_substr($str, $start, $length, 'UTF-8');

// 範例
$str = 'Hello 世界 😀';
echo mb_substr($str, 0, 6);      // Hello 世
echo mb_substr($str, 6, 2);      // 界
echo mb_substr($str, 8);         //  😀 (含空格)
echo mb_substr($str, -3);        // 界 😀 (負數從尾部算起)
?>

封裝通用截斷函式 (支援尾碼、HTML 標籤保護)

<?php
/**
 * 多位元組安全截取
 * @param string $str 來源字串
 * @param int $length 最大字元數
 * @param string $suffix 截斷尾碼
 * @param bool $stripTags 是否先移除 HTML 標籤
 * @param string $encoding 編碼
 */
function mb_truncate($str, $length = 100, $suffix = '...', $stripTags = true, $encoding = 'UTF-8') {
    if ($stripTags) {
        $str = strip_tags($str);
    }
    $str = html_entity_decode($str, ENT_QUOTES, $encoding); // 解碼實體
    $str = preg_replace('/\s+/', ' ', $str); // 合併空白
    
    if (mb_strlen($str, $encoding) <= $length) {
        return $str;
    }
    return mb_substr($str, 0, $length, $encoding) . $suffix;
}

// 測試
$text = '
這是一段測試內容 😀🎉
';
echo mb_truncate($text, 10); // 這是一段測試內...
?>

方案二：grapheme_substr() 處理 Emoji 與組合字元 (PHP 7.0+ intl)

為什麼需要 Grapheme？
😀 = 1 字元 (U+1F600)
👨‍👩‍👧‍👦 = 1 字素簇，但由 7 個 Unicode 碼位組成 (ZWJ 序列)
é = 1 字素簇，可能是 1 碼位 (U+00E9) 或 2 碼位 (e + U+0301 組合銳音符)

<?php
$str = 'A👨‍👩‍👧‍👦BéC'; // A + 家庭表情 + B + é + C

echo "mb_strlen: "    . mb_strlen($str);    // 10 (碼位數)
echo "grapheme_strlen: " . grapheme_strlen($str); // 5 (視覺字元數)

echo "mb_substr(0,3): "    . mb_substr($str, 0, 3);    // A👨 (截斷表情!)
echo "grapheme_substr(0,3): " . grapheme_substr($str, 0, 3); // A👨‍👩‍👧‍👦B (完整視覺單位)
?>

方案三：無擴展環境的 UTF-8 正則備援

<?php
function utf8_substr_regex($str, $start, $length = null) {
    // 非貪婪匹配 UTF-8 字元序列
    $pattern = '/([\x00-\x7F]|[\xC0-\xDF][\x80-\xBF]|[\xE0-\xEF][\x80-\xBF]{2}|[\xF0-\xF7][\x80-\xBF]{3})/';
    preg_match_all($pattern, $str, $matches);
    $chars = $matches[0];
    $slice = array_slice($chars, $start, $length);
    return implode('', $slice);
}

// 效能較 mb_substr 低 5-10 倍，僅作無擴展環境備援
?>

方案四：GBK/Big5 舊專案專用位元組掃描

<?php
function gbk_substr($str, $start, $length) {
    $result = '';
    $strlen = strlen($str);
    $count = 0;
    for ($i = 0; $i < $strlen && $count < $start + $length; $i++) {
        if ($count >= $start) $result .= $str[$i];
        if (ord($str[$i]) > 0x80) { // 雙位元組字元
            $i++;
            if ($count >= $start) $result .= $str[$i];
        }
        $count++;
    }
    return $result;
}
?>

HTML 內容截取進階：保留標籤結構完整

<?php
function html_truncate($html, $maxLength, $suffix = '...') {
    $dom = new DOMDocument();
    @$dom->loadHTML('' . $html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
    
    $xpath = new DOMXPath($dom);
    $textNodes = iterator_to_array($xpath->query('//text()'));
    
    $currentLen = 0;
    foreach ($textNodes as $node) {
        $text = $node->nodeValue;
        $textLen = mb_strlen($text);
        
        if ($currentLen + $textLen <= $maxLength) {
            $currentLen += $textLen;
            continue;
        }
        
        // 需在這個文字節點截斷
        $remain = $maxLength - $currentLen;
        if ($remain > 0) {
            $node->nodeValue = mb_substr($text, 0, $remain) . $suffix;
        } else {
            $node->nodeValue = $suffix;
        }
        // 移除後續所有文字節點
        $next = $node->nextSibling;
        while ($next) {
            $toRemove = $next;
            $next = $next->nextSibling;
            if ($toRemove->nodeType === XML_TEXT_NODE) {
                $toRemove->parentNode->removeChild($toRemove);
            }
        }
        break;
    }
    
    return $dom->saveHTML();
}
?>

效能基準測試 (100 萬次循環，PHP 8.2)

選型建議

1. 現代專案 (PHP 7.2+)：裝 intl 擴展，直接用 grapheme_substr() — 正確、快速、支援 Emoji。
2. 相容舊環境：mb_substr() + mb_internal_encoding('UTF-8') — 穩定、廣泛支援。
3. HTML 富文本：用 DOMDocument 解析後截取文字節點，輸出完整 HTML 片段。
4. 極致效能 (億級處理)：C 擴展或 Swoole 協程 + 自訂位元組掃描。