mail() **依賴本地 MTA (Sendmail/Postfix)**,Windows 環境通常無法工作PHPMailer 是事實標準:純 PHP 實現、SMTP 直連、功能完整、活躍維護、Composer 安裝。
composer require phpmailer/phpmailer
// 入口文件
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;
require 'vendor/autoload.php';
<?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;
}
?>
<?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 = '
';
// 純文本替代版 (郵件客戶端不支援 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 中:
// 自定義標頭
$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 Host | Port | Encryption | 備註 |
|---|---|---|---|---|
| Gmail | smtp.gmail.com | 587 | STARTTLS | **必須開啟「兩步驟驗證」並生成「應用程式密碼」** |
| Outlook/Hotmail/Live | smtp.office365.com | 587 | STARTTLS | 同樣需應用密碼 |
| Yahoo | smtp.mail.yahoo.com | 465 | SSL | 需開啟「不太安全的應用」或應用密碼 |
| 163/126/Yeah.net | smtp.163.com | 465/994 | SSL | 需開啟 SMTP 服務並設「客戶端授權密碼」 |
| QQ/企業郵箱 | smtp.qq.com / smtp.exmail.qq.com | 465/587 | SSL/STARTTLS | 需開啟 SMTP 獲取授權碼 |
| 自建 Postfix/Exim | mail.yourdomain.com | 587/465/25 | STARTTLS/SSL/無 | 需配置 SPF/DKIM/DMARC、rDNS、IP 信譽 |
| SendGrid/Mailgun/Amazon SES | smtp.sendgrid.net 等 | 587/2525 | STARTTLS | API Key 作為 Password,用戶名固定 (apikey/postmaster) |
$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(); // 最後關閉連線
**HTTP 請求中直接發送郵件會阻塞響應 (2-10 秒),用戶體驗極差,且易超時失敗。**
架構:
// 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); // 瞬間返回響應
不要在代碼中拼接 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;
| 錯誤訊息 | 可能原因 | 解決方向 |
|---|---|---|
| SMTP connect() failed | 網路不通、埠被防火牆攔截、Host/Port/Encryption 錯誤 | telnet 測試連通性、檢查防火牆/安全組、核對服務商文檔 |
| Authentication failed | 帳號/密碼錯誤、未用應用密碼、SMTP 未啟用 | 確認應用密碼、服務商後台開啟 SMTP/IMAP |
| SSL certificate verify failed | CA 憑證缺失、系統時間錯誤、自簽憑證 | 更新 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 請求中絕不直接發送郵件,必須佇列化。**