PHP `iconv()`「Unknown error (22)」陷阱：編碼名稱大小寫與標準化的關鍵差異

調用 `iconv('gbk', 'utf8', $str)` 拋出 `Notice: iconv(): Unknown error (22)`，改為 `iconv('gbk', 'utf-8', $str)` 即正常。根因：**目標編碼名稱必須符合 IANA 標準別名**，`utf8` 非標準名，`utf-8` 才是。

錯誤復現

<?php
$str = "嘿嘿";
iconv('gbk', 'utf8', $str);   // ❌ PHP Notice: iconv(): Unknown error (22)
iconv('gbk', 'utf-8', $str);  // ✅ 正常輸出

根因分析

• `iconv` 依賴系統 `libiconv` / `glibc iconv` 實現，編碼名稱解析遵循 **IANA Character Sets** 註冊表。
• 標準名：**`UTF-8`**（大小寫不敏感，推薦 `UTF-8` 或 `utf-8`）。
• `utf8`、`utf_8`、`utf8mb4` (MySQL 專用) 均**非標準 iconv 編碼名**，導致 `iconv_open()` 失敗，返回 `EINVAL` (22)。

常見編碼名稱對照表

最佳實踐

1. 統一使用標準名：代碼規範強制 `utf-8`、`gbk` 等標準寫法，Code Review / 靜態分析攔截非標準名。
2. 封裝轉碼工具函數：

   function safe_iconv($in_charset, $out_charset, $str) {
       static $alias_map = [
           'utf8' => 'utf-8', 'utf_8' => 'utf-8',
           'gb2312' => 'gbk', // 視業務決定是否自動映射
       ];
       $out_charset = $alias_map[strtolower($out_charset)] ?? $out_charset;
       $in_charset  = $alias_map[strtolower($in_charset)] ?? $in_charset;
       return @iconv($in_charset, $out_charset.'//IGNORE//TRANSLIT', $str) ?: $str;
   }
   

3. 優先使用 `mb_convert_encoding()`**：`mbstring` 內部別名表更豐富，容錯性更好（如接受 `utf8`），且不依賴系統 `iconv` 實現差異。
4. 單元測試覆蓋編碼轉換**：包含中文、稀有字、Emoji、控制字符等邊界用例。

環境差異提示

• Windows `php_iconv.dll` 通常基於 `libiconv`，嚴格遵循 IANA 名。
• Linux `glibc iconv` 別名表較豐富，某些發行版可能接受 `utf8`，**但不可依賴**，跨平台部署必現問題。
• PHP 版本不影響此行為（測試環境：libiconv-1.13.1 + PHP 5.3.8）。

總結

**`iconv` 編碼名稱區分大小寫且要求標準化**——`utf-8` ✅，`utf8` ❌。養成「複製 IANA 標準名」習慣，封裝統一入口，徹底杜絕 error 22。