萬盛學電腦網

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

PHP 字符編碼轉換:`mb_convert_encoding` 與 `iconv` 選型、安裝與避坑指南

遷移至 Nginx+PHP-FPM 後報 `Call to undefined function mb_convert_encoding()`,原因是缺少 `mbstring` 擴展。本文對比 `mbstring` 與 `iconv` 兩大編碼轉換庫的安裝、API 差異、效能、邊界處理,給出選型建議。

擴展安裝(以 PHP 5.3 為例,現代版本同理)

# 1. 進入原始碼擴展目錄
cd /usr/src/php-5.3.28/ext/mbstring

# 2. phpize 生成 configure
/usr/local/php/bin/phpize

# 3. 配置、編譯、安裝
./configure --with-php-config=/usr/local/php/bin/php-config
make && make install

# 4. 啟用擴展
echo 'extension=mbstring.so' >> /usr/local/php/etc/php.ini
# 或建議獨立 ini:echo 'extension=mbstring.so' > /usr/local/php/etc/conf.d/mbstring.ini

# 5. 重載 PHP-FPM
systemctl reload php-fpm

`iconv` 同理:`cd ../iconv && phpize && ./configure --with-iconv=/usr/local --with-php-config=... && make install`。

核心函式對比

特性mb_convert_encodingiconv
所屬擴展mbstringiconv (通常內建)
函式簽名`mb_convert_encoding(string $str, string $to, string|null $from=null)``iconv(string $from, string $to, string $str)`
自動偵測來源編碼支援 `mb_detect_encoding()` 配合不支援,必須指定 from
非法字元處理預設替換為 `?`,可設 `mb_substitute_character()``//IGNORE` 忽略、`//TRANSLIT` 近似轉換
效能略慢(功能豐富)極快(C 底層直接映射)
支援編碼數量100+150+(依系統 libiconv)

常見編碼轉換範例

<?php
// GBK → UTF-8
$utf8 = mb_convert_encoding($gbkStr, 'UTF-8', 'GBK');
$utf8 = iconv('GBK', 'UTF-8//IGNORE', $gbkStr); // 推薦加 //IGNORE

// UTF-8 → GBK(含特殊字元如 — · ’)
$gbk = iconv('UTF-8', 'GBK//IGNORE', $utf8);   // GBK 比 GB2312 字符集大,建議用 GBK

// Big5 ↔ GB2312
$big5 = mb_convert_encoding($gb2312, 'Big5', 'GB2312');
$gb2312 = iconv('Big5', 'GB2312//IGNORE', $big5);

// 批次轉換陣列
function convertArray(array $data, string $to, string $from): array
{
    array_walk_recursive($data, function(& $v) use ($to, $from) {
        if (is_string($v)) $v = mb_convert_encoding($v, $to, $from);
    });
    return $data;
}
?>

避坑指南

  1. 來源編碼未知:用 `mb_detect_encoding($str, ['UTF-8','GBK','GB2312','BIG5'], true)` 嚴格模式偵測,失敗則拋錯/記錄人工介入。
  2. `iconv` 遇 `//IGNORE` 仍截斷:部分系統 `libiconv` 版本 Bug,改用 `mb_convert_encoding` 或升級 `libiconv`。
  3. 資料庫連線編碼:PDO DSN 加 `charset=utf8mb4`,執行 `SET NAMES utf8mb4`,源頭統一 UTF-8 可避免 90% 轉碼需求。
  4. 輸出頁面編碼:`header('Content-Type: text/html; charset=UTF-8')` + 檔案存 UTF-8 無 BOM。
  5. 大檔案轉碼:分塊讀取 `iconv` 流式轉換,避免一次性載入記憶體。

選型建議

  • 新專案/現代框架:統一 UTF-8,極少需轉碼;若需轉碼優先 `mbstring`(API 友善、自動偵測)。
  • 高效能/流式/舊系統互通:`iconv` + `//IGNORE`,速度快、依賴少。
  • Docker/雲原生:基礎鏡像 `php:8.3-fpm` 已預裝 `mbstring`、`iconv`、`intl`,無需手動編譯。

編碼問題 90% 來自「源頭不統一」。建立「全鏈路 UTF-8」規範,轉碼只作為邊界兼容手段。

copyright © 萬盛學電腦網 all rights reserved