萬盛學電腦網

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

PHPMailer 完整配置指南:SMTP 認證、SSL/TLS、附件、HTML 郵件、佇列與錯誤診斷

為什麼不直接用 mail()?

  • mail() **依賴本地 MTA (Sendmail/Postfix)**,Windows 環境通常無法工作
  • **無 SMTP 認證**,郵件極易進垃圾箱或被拒收 (SPF/DKIM/DMARC 驗證失敗)
  • **不支援 HTML/附件/內嵌圖片/多收件人/抄送/密送/優先級/自定義標頭**
  • **無調試能力**,發送失敗無日誌、無錯誤詳情

PHPMailer 是事實標準:純 PHP 實現、SMTP 直連、功能完整、活躍維護、Composer 安裝。

安裝與基本引入

composer require phpmailer/phpmailer

// 入口文件
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

核心配置模板:Gmail / Outlook / 企業郵箱 / 自建郵件服務器

<?php
function createMailer(): PHPMailer
{
    $mail = new PHPMailer(true); // true = 啟用異常拋出

    // === 核心 SMTP 設定 ===
    $mail->isSMTP();                                    // 使用 SMTP
    $mail->Host       = 'smtp.gmail.com';               // SMTP 服務器
    $mail->SMTPAuth   = true;                           // 啟用認證
    $mail->Username   = 'your_email@gmail.com';         // 完整郵箱地址
    $mail->Password   = 'your_app_password';            // **應用專用密碼** (非登入密碼!)
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; // TLS 加密 (587 埠)
    $mail->Port       = 587;                            // TLS 埠
    // 或者 SSL 加密 (465 埠)
    // $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; 
    // $mail->Port       = 465;

    // === 發件人/回覆地址 (關鍵:必須與 SMTP 用戶一致或經驗證) ===
    $mail->setFrom('your_email@gmail.com', '您的應用名稱');
    $mail->addReplyTo('reply@example.com', '回覆處理');

    // === 編碼與語言 ===
    $mail->CharSet = 'UTF-8';                           // **必須設定**,否則中文亂碼
    $mail->setLanguage('zh_cn');                        // 錯誤訊息中文化 (需 language/ 目錄)

    // === 除錯模式 (開發/測試階段開啟) ===
    // $mail->SMTPDebug = SMTP::DEBUG_SERVER;            // 0=關閉, 1=客戶端, 2=客戶端+服務端, 3=完整溝通, 4=低層級
    // $mail->Debugoutput = function($str, $level) { error_log("PHPMailer [$level]: $str"); }; // 自定義輸出

    return $mail;
}
?>

發送 HTML 郵件 + 純文本替代 + 附件 + 內嵌圖片

<?php
$mail = createMailer();

try {
    // 收件人
    $mail->addAddress('user@example.com', '用戶名稱');
    $mail->addCC('cc@example.com', '抄送人');
    $mail->addBCC('bcc@example.com', '密送人'); // 隱藏

    // 主旨
    $mail->Subject = '🎉 歡迎註冊 - 您的專屬優惠碼';

    // HTML 內容 (支援完整 HTML/CSS)
    $mail->isHTML(true);
    $mail->Body = '
        

歡迎加入我們,' . htmlspecialchars($userName) . '!

您的專屬優惠碼:' . $couponCode . '

立即使用優惠


此郵件由系統自動發送,請勿直接回覆。

'; // 純文本替代版 (郵件客戶端不支援 HTML 時顯示,反垃圾評分加分項) $mail->AltBody = "歡迎加入,{$userName}!\n您的優惠碼:{$couponCode}\n請訪問 https://shop.example.com/use/{$couponCode} 使用。"; // 附件 $mail->addAttachment('/path/to/invoice.pdf', 'Invoice_202401.pdf'); // 重命名 $mail->addAttachment('/path/to/large.zip'); // 原名 // 字串作為附件 (不寫入磁盤) $mail->addStringAttachment($pdfContent, 'dynamic_report.pdf', 'base64', 'application/pdf'); // 內嵌圖片 (HTML 中用 cid:logo 引用) $mail->addEmbeddedImage('/path/to/logo.png', 'logo', 'logo.png'); // cid:logo // HTML 中: Logo // 自定義標頭 $mail->addCustomHeader('X-Mailer-Category', 'welcome_email'); $mail->addCustomHeader('List-Unsubscribe', ''); // 發送! $mail->send(); echo "郵件發送成功!Message-ID: {$mail->getLastMessageID()}"; } catch (Exception $e) { // 詳細錯誤資訊 echo "發送失敗: {$mail->ErrorInfo}"; // 記錄完整日誌 error_log("PHPMailer Error: {$mail->ErrorInfo}\nSMTP Transcript:\n" . $mail->getSMTPInstance()->getTransactionLog()); } ?>

常見服務商 SMTP 設定速查表

服務商SMTP HostPortEncryption備註
Gmailsmtp.gmail.com587STARTTLS**必須開啟「兩步驟驗證」並生成「應用程式密碼」**
Outlook/Hotmail/Livesmtp.office365.com587STARTTLS同樣需應用密碼
Yahoosmtp.mail.yahoo.com465SSL需開啟「不太安全的應用」或應用密碼
163/126/Yeah.netsmtp.163.com465/994SSL需開啟 SMTP 服務並設「客戶端授權密碼」
QQ/企業郵箱smtp.qq.com / smtp.exmail.qq.com465/587SSL/STARTTLS需開啟 SMTP 獲取授權碼
自建 Postfix/Eximmail.yourdomain.com587/465/25STARTTLS/SSL/無需配置 SPF/DKIM/DMARC、rDNS、IP 信譽
SendGrid/Mailgun/Amazon SESsmtp.sendgrid.net 等587/2525STARTTLSAPI Key 作為 Password,用戶名固定 (apikey/postmaster)

進階功能與最佳實踐

1. 批量發送:重用 SMTP 連線 (極大提升效能)

$mail = createMailer();
$mail->SMTPKeepAlive = true; // 保持連線不斷開

foreach ($users as $user) {
    // 重置收件人/內容相關屬性
    $mail->clearAddresses();
    $mail->clearAttachments();
    $mail->clearCustomHeaders();
    
    $mail->addAddress($user['email'], $user['name']);
    $mail->Subject = "專屬推薦給 {$user['name']}";
    $mail->Body = renderTemplate('recommend', $user);
    $mail->AltBody = strip_tags($mail->Body);
    
    try {
        $mail->send();
        // 記錄成功
    } catch (Exception $e) {
        // 記錄失敗,繼續下一個
    }
}
$mail->smtpClose(); // 最後關閉連線

2. 非同步/佇列發送 (生產環境必須)

**HTTP 請求中直接發送郵件會阻塞響應 (2-10 秒),用戶體驗極差,且易超時失敗。**

架構:

  1. 控制器:將郵件數據 (to, subject, template, data) 推入 **Redis/RabbitMQ/Database Queue**
  2. Worker (CLI 持久進程/Supervisor 管理):消費佇列,實例化 PHPMailer 發送
  3. 失敗重試:指數退避、死信佇列、告警通知
// Laravel Queue 範例 (概念同理)
class SendWelcomeEmail implements ShouldQueue
{
    use Queueable, SerializesModels;
    public $user;
    public function handle() {
        Mail::to($this->user->email)->send(new WelcomeEmail($this->user));
    }
}
// 控制器: SendWelcomeEmail::dispatch($user); // 瞬間返回響應

3. 郵件模板引擎分離

不要在代碼中拼接 HTML 字串。使用 **Blade / Twig / Latte / Plates** 等模板引擎:

// views/emails/welcome.blade.php


{{ $subject }}

    

歡迎,{{ $user->name }}!

您的優惠碼:{{ $coupon }}

// 發送時 $html = view('emails.welcome', ['user' => $user, 'coupon' => $code])->render(); $text = view('emails.welcome_text', ['user' => $user, 'coupon' => $code])->render(); $mail->Body = $html; $mail->AltBody = $text;

4. 郵件送達率優化清單 (Checklist)

  • ✅ **SPF 記錄**:`v=spf1 include:_spf.google.com ~all` (授權發送 IP)
  • ✅ **DKIM 簽名**:郵件內容簽名,防竄改 (服務商通常自動處理)
  • ✅ **DMARC 策略**:`v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com`
  • ✅ **rDNS (PTR 記錄)**:發送 IP 反向解析指向郵件域名
  • ✅ **List-Unsubscribe 標頭**:單鍵退訂,減少投訴
  • ✅ **避免垃圾郵件關鍵詞**:免費、贏獎、點擊這裡、大量大寫/表情符號
  • ✅ **文字/HTML 比例平衡**:別只發圖片或純 HTML
  • ✅ **監控退信/投訴率**:> 0.1% 投訴率會損害 IP 信譽

常見錯誤診斷速查

錯誤訊息可能原因解決方向
SMTP connect() failed網路不通、埠被防火牆攔截、Host/Port/Encryption 錯誤telnet 測試連通性、檢查防火牆/安全組、核對服務商文檔
Authentication failed帳號/密碼錯誤、未用應用密碼、SMTP 未啟用確認應用密碼、服務商後台開啟 SMTP/IMAP
SSL certificate verify failedCA 憑證缺失、系統時間錯誤、自簽憑證更新 ca-certificates、同步 NTP、或暫時設 SMTPOptions verify_peer=false (不推薦)
Message could not be sent. Mailer Error: ...被服務商拒收 (垃圾箱、頻率限制、內容違規)檢查退信代碼、優化內容、降低發送頻率、申請專用 IP
中文亂碼未設 $mail->CharSet = 'UTF-8'強制設定 UTF-8,確保模板檔案也是 UTF-8 編碼
附件亂碼/無法打開編碼錯誤、Content-Type 不符、檔案損壞用 addStringAttachment 指定 base64 編碼、正確 MIME 類型

結語

**PHPMailer 是 PHP 發送郵件的專業標準配置**。掌握 **SMTP 認證模式 (STARTTLS/SSL)、HTML+Text 多部分、附件/內嵌圖片、批量重用連線、非同步佇列架構、SPF/DKIM/DMARC 送達率優化**,即可構建企業級、高送達、可維護的郵件系統。**切記:HTTP 請求中絕不直接發送郵件,必須佇列化。**

copyright © 萬盛學電腦網 all rights reserved