Laravel 9.x 邮件发送失败：Mailgun 未定义错误的完整解决方案-php教程-PHP中文网

Laravel 9.x 邮件发送失败：Mailgun 未定义错误的完整解决方案

Laravel 9 中配置 Mailgun 发送邮件时出现 “Mailgun not defined” 错误，根本原因是 .env 中误设 MAIL_MAILER=Mailgun，但 config/mail.php 并未启用 Mailgun 官方驱动（缺少 API 凭据与服务注册），实际应使用 SMTP 方式对接 Mailgun。

laravel 9 中配置 mailgun 发送邮件时出现 “mailgun not defined” 错误，根本原因是 `.env` 中误设 `mail_mailer=mailgun`，但 `config/mail.php` 并未启用 mailgun 官方驱动（缺少 api 凭据与服务注册），实际应使用 smtp 方式对接 mailgun。

该错误并非代码逻辑缺陷，而是 Laravel 邮件驱动配置不匹配导致的运行时异常。Laravel 的 MAIL_MAILER 环境变量必须与 config/mail.php 中已声明的 mailer 键名完全一致且已正确定义。当前 .env 设置为：

MAIL_MAILER=Mailgun

但 config/mail.php 中虽存在 'mailgun' => [...] 配置块，其键名为小写 mailgun，而 Laravel 对 mailer 名称严格区分大小写，且更重要的是：'mailgun' 驱动需配合 Mailgun SDK 和 API 密钥使用，不能仅靠 SMTP 凭据启用。你提供的 .env 实际配置的是 Mailgun 的 SMTP 服务（smtp.mailgun.org），因此应统一使用 smtp 驱动，而非虚构的 Mailgun 驱动名。

✅ 正确做法如下：

1. 修正 .env 邮件配置（推荐 SMTP 模式）

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your-sandbox@YOUR_DOMAIN.mailgun.org  # 替换为你的 Mailgun SMTP 用户名（通常是 sandbox 地址）
MAIL_PASSWORD=your_mailgun_smtp_password            # 在 Mailgun 控制台获取的 SMTP password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-sandbox@YOUR_DOMAIN.mailgun.org
MAIL_FROM_NAME="${APP_NAME}"

⚠️ 注意：

MAIL_USERNAME 必须是 Mailgun 控制台中 SMTP Credentials 下显示的完整邮箱（如 postmaster@sandbox123abc.mailgun.org），不是你的个人邮箱；

MAIL_PASSWORD 是 Mailgun 生成的专用 SMTP 密码（非账户密码），在 Mailgun Dashboard → Domain → SMTP Credentials 中查看；

确保该域名已在 Mailgun 验证并通过 DNS 配置（尤其对 sandbox 域名，收件人邮箱必须在 Mailgun 的 Authorized Recipients 列表中，或升级到已验证域名）。

2. 确保 config/mail.php 中 smtp 驱动配置完整（无需修改 mailgun 块）
你的当前配置基本正确，但建议显式补充 MAIL_FROM_ADDRESS 和 encryption，并验证 smtp 是默认驱动：

'default' => env('MAIL_MAILER', 'smtp'),

'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
        'port' => env('MAIL_PORT', 587),
        'encryption' => env('MAIL_ENCRYPTION', 'tls'),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
        'timeout' => null,
        'auth_mode' => null,
    ],
    // 'mailgun' => [...]  // 此块可保留，但当前无需启用
],

3. 修复邮件类中的属性命名错误（关键 Bug）
在 app/Mail/contacter.php 中，构造函数接收 $emailData 并赋值给 $this->mailData，但 build() 方法中引用的是 $this->emailData —— 属性名不一致导致视图无法解析数据：

// ❌ 错误：构造函数赋值给 $this->mailData，但视图用 $emailData
public function __construct($emailData)
{
    $this->mailData = $emailData; // ← 应改为 $this->emailData
}

// ✅ 正确写法：
public function __construct($emailData)
{
    $this->emailData = $emailData; // ← 保持与 public 属性和 Blade 中变量名一致
}

4. 清除配置缓存（部署后必需）
每次修改 .env 或 config/ 文件后，务必执行：

php artisan config:clear
php artisan cache:clear
# 开发环境可加 --no-cache 跳过缓存（调试用）

5. 可选：启用 Mailgun 原生驱动（进阶）
若需使用 Mailgun API（而非 SMTP），需安装官方包并注册服务：

composer require mailgun/mailgun-php guzzlehttp/psr7

并在 config/mail.php 中配置：

'mailgun' => [
    'transport' => 'mailgun',
    'domain' => env('MAILGUN_DOMAIN'),      // e.g., 'sandbox123abc.mailgun.org'
    'secret' => env('MAILGUN_SECRET'),      // API Key，格式为 'key-xxx'
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
],

同时在 .env 中添加：

MAILGUN_DOMAIN=sandbox123abc.mailgun.org
MAILGUN_SECRET=key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

然后将 MAIL_MAILER=mailgun —— 但此方式需额外处理 Webhook、日志和错误追踪，对新手而言 SMTP 更简单稳定。

? 总结：
“Mailgun not defined” 错误本质是驱动名称不匹配 + 配置错位。优先采用 SMTP 模式，确保 .env 中 MAIL_MAILER=smtp，MAIL_USERNAME 和 MAIL_PASSWORD 为 Mailgun 提供的真实 SMTP 凭据，并修正邮件类属性名。完成配置后，使用 php artisan tinker 快速测试：

Mail::raw('Test from Laravel!', function ($message) {
    $message->to('your-verified-email@example.com')->subject('Mailgun Test');
});

只要 SMTP 凭据有效且收件邮箱已授权，即可成功发送。