PHPMailer 中文亂碼終極解決方案：三步徹底修正編碼問題

PHPMailer 發送中文郵件出現亂碼，90% 是編碼設定不一致導致。本文提供經驗證的三步修正法，涵蓋核心庫配置、實例層級設定、標題專用編碼，確保 Gmail、Outlook、QQ 郵箱等國際/國內主流客戶端完美顯示。

步驟 1：修改核心庫預設字符集 (一次修正，全域生效)

編輯 vendor/phpmailer/phpmailer/src/PHPMailer.php (或舊版 class.phpmailer.php)：

// 找到約第 100 行
public $CharSet = 'iso-8859-1';  // 預設西歐編碼

// 修改為
public $CharSet = 'UTF-8';

原理：ISO-8859-1 僅支援西歐字符，中文會被誤解析為亂碼。UTF-8 涵蓋全球所有語言，是郵件傳輸的國際標準編碼 (RFC 6532)。

步驟 2：實例化時顯式宣告字符集 (雙重保險)

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);
try {
    // 核心編碼設定
    $mail->CharSet = 'UTF-8';          // 郵件正文編碼
    $mail->Encoding = 'base64';        // 內容傳輸編碼，避免 8bit 被郵遞伺服器截斷

    // SMTP 設定 (以 Gmail 為例)
    $mail->isSMTP();
    $mail->Host = 'smtp.gmail.com';
    $mail->SMTPAuth = true;
    $mail->Username = 'your@gmail.com';
    $mail->Password = 'app_password';  // 應用程式密碼
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
    $mail->Port = 587;

    // 寄件/收件
    $mail->setFrom('your@gmail.com', '您的名稱');
    $mail->addAddress('recipient@example.com');

    // 內容
    $mail->isHTML(true);
    $mail->Subject = '測試中文標題';
    $mail->Body    = '這是 HTML 格式的中文正文內容。';
    $mail->AltBody = '這是純文字備用內容。';

    $mail->send();
    echo '發送成功';
} catch (Exception $e) {
    echo "發送失敗: {$mail->ErrorInfo}";
}

步驟 3：標題專用 Base64 編碼 (解決 Gmail/Outlook 標題亂碼)

即使正文正常，標題若含中文，部分 MUAs (郵件用戶代理) 仍會亂碼。RFC 2047 規定標題需用 =?charset?encoding?encoded-text?= 格式。

// 手動編碼 (PHPMailer 6.5+ 內建支援，若版本舊請手動)
$subject = '中文標題測試';
$mail->Subject = '=?UTF-8?B?' . base64_encode($subject) . '?=';
// 產生：=?UTF-8?B?5L2g5aW95Lit5b+D5Lq655S1?=

進階封裝函數：

function encodeMimeSubject(string $subject, string $charset = 'UTF-8'): string
{
    return '=?' . $charset . '?B?' . base64_encode($subject) . '?=';
}

// 使用
$mail->Subject = encodeMimeSubject('訂單 #20240520 發貨通知');

常見誤區避坑

除錯檢查清單

1. 原始郵件來源 (Show Original) 中 Content-Type: text/html; charset=UTF-8 是否存在？
2. Subject: =?UTF-8?B?....?= 格式是否正確？
3. SMTP 通訊過程中是否有 DATA 命令後內容截斷？(檢查 Encoding = 'base64')
4. 資料庫/模板讀取的字串本身是否已為 UTF-8？(mb_check_encoding($str, 'UTF-8'))

遵循「核心庫 UTF-8 + 實例 UTF-8 + 標題 Base64」三步法，PHPMailer 中文亂碼問題將徹底成為歷史。