PHP 只替換一次或 N 次：preg_replace limit 參數與自定義函數實現

核心方案：preg_replace 第 4 參數 limit

簽名：preg_replace(mixed $pattern, mixed $replacement, mixed $subject, int $limit = -1, int &$count = null)

方案二：str_replace_once —— 手動定位 + substr_replace
function str_replace_limit($search, $replace, $subject, $limit = -1) {
    // 構建安全正則：轉義特殊字符
    if (is_array($search)) {
        $search = array_map(function($s) { return '`' . preg_quote($s, '`') . '`'; }, $search);
    } else {
        $search = '`' . preg_quote($search, '`') . '`';
    }
    return preg_replace($search, $replace, $subject, $limit);
}

// 測試
echo str_replace_limit('b', 'X', 'abcabbc', 2);  // aXcaXbc
echo str_replace_limit(['a','b'], ['A','B'], 'abcabbc', 3);  // ABcABbc

優點：API 近似 str_replace、支持數組、自動轉義、支持 limit。

方案四：strtr + 截取技巧（特定場景）
function mb_str_replace_once($search, $replace, $subject, $encoding = 'UTF-8') {
    $pos = mb_strpos($subject, $search, 0, $encoding);
    if ($pos === false) return $subject;
    return mb_substr($subject, 0, $pos, $encoding) 
         . $replace 
         . mb_substr($subject, $pos + mb_strlen($search, $encoding), null, $encoding);
}


總結
preg_replace $limit 參數是原生、通用、正則友好的首選。固定字符串高頻場景用 str_replace_once（手動定位）或 str_replace_limit（封裝轉義）獲得更好性能與 API 體驗。多字節環境務必用 mb_strpos/mb_substr 避免截斷字符。