PHPMailer 完整使用指南：從安裝到 Gmail SMTP 實戰

PHPMailer 核心特性

• ✅ SMTP 驗證 / SSL / TLS 加密傳輸
• ✅ HTML/純文字多格式郵件
• ✅ 多附件、嵌入圖片、CC/BCC/回覆地址
• ✅ 多語言、字元編碼 (UTF-8) 完整支援
• ✅ 除錯模式、自定義 Header、郵件佇列
• ✅ 相容 Gmail、Outlook、Sendmail、Postfix 等

安裝方式 (推薦 Composer)

composer require phpmailer/phpmailer

Gmail SMTP 完整實作範例

<?php
require_once __DIR__ . '/vendor/autoload.php';

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

function sendMail(array $to, string $subject, string $body, array $attachments = []): bool
{
    $mail = new PHPMailer(true);
    
    try {
        // === 伺服器設定 ===
        $mail->SMTPDebug = SMTP::DEBUG_OFF;  // 開發時可用 DEBUG_SERVER
        $mail->isSMTP();
        $mail->Host       = 'smtp.gmail.com';
        $mail->SMTPAuth   = true;
        $mail->Username   = 'your_email@gmail.com';      // Gmail 帳號
        $mail->Password   = 'your_app_password';         // 應用程式密碼 (非登入密碼)
        $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; // SSL (port 465)
        $mail->Port       = 465;
        $mail->CharSet    = 'UTF-8';
        
        // === 寄件人/收件人 ===
        $mail->setFrom('your_email@gmail.com', '系統名稱');
        foreach ($to as $addr => $name) {
            $mail->addAddress($addr, $name);
        }
        $mail->addReplyTo('reply@example.com', '回覆名稱');
        
        // === 郵件內容 ===
        $mail->isHTML(true);
        $mail->Subject = $subject;
        $mail->Body    = $body;
        $mail->AltBody = strip_tags($body);  // 純文字備用
        
        // === 附件處理 ===
        foreach ($attachments as $path => $name) {
            $mail->addAttachment($path, $name);
        }
        
        $mail->send();
        return true;
        
    } catch (Exception $e) {
        error_log("Mailer Error: {$mail->ErrorInfo}");
        return false;
    }
}

// === 使用範例 ===
$sent = sendMail(
    ['user@example.com' => '使用者名稱'],
    '測試主旨',
    '<h1>HTML 內容</h1><p>支援中文</p>',
    ['/path/file.pdf' => '報表.pdf']
);

echo $sent ? '寄送成功' : '寄送失敗';

關鍵設定說明

常見問題排查

• 認證失敗：確認開啟「兩步驟驗證」並產生「應用程式密碼」
• 連線逾時：檢查防火牆/雲端安全群組是否開放 465/587 埠
• 中文亂碼：設定 `$mail->CharSet = 'UTF-8'` 且檔案存為 UTF-8
• 進垃圾信箱：設定 SPF/DKIM/DMARC、避免垃圾郵件關鍵字、使用專用域名

進階功能範例

嵌入圖片 (CID)

$mail->addEmbeddedImage('/path/logo.png', 'logo_cid');
$mail->Body = '<img src="cid:logo_cid" alt="Logo">';

批次寄送 (效能優化)

$mail->SMTPKeepAlive = true;  // 保持連線
foreach ($users as $user) {
    $mail->clearAddresses();
    $mail->addAddress($user['email'], $user['name']);
    $mail->Body = str_replace('{{name}}', $user['name'], $template);
    $mail->send();
}

安全提醒：勿將帳密寫死程式碼，請使用環境變數 ($_ENV 或 getenv()) 或密鑰管理系統。