Laravel¶

适用于 Laravel（10.x 和 11.x）应用的集成指南。Mailexam 作为标准 SMTP 服务器接入——只需修改 .env 中的配置；发送代码（Mail、Mailable、队列）保持不变。

前置条件¶

Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
已配置邮件模块的 Laravel 应用（默认使用 config/mail.php）。

从项目的欢迎邮件（或控制台）中复制：

YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
邮件中的主机 — YOUR_LOGIN.mailexam.cn（主机名与登录名一致）。

1. 配置 `.env`¶

添加或更新邮件相关变量：

MAIL_MAILER=smtp
MAIL_HOST=YOUR_LOGIN.mailexam.cn
MAIL_PORT=587
MAIL_USERNAME=YOUR_LOGIN
MAIL_PASSWORD=YOUR_PASSWORD
MAIL_ENCRYPTION=tls

MAIL_FROM_ADDRESS=noreply@example.test
MAIL_FROM_NAME="${APP_NAME}"

发件人地址

MAIL_FROM_ADDRESS 可以是任意测试地址——邮件仍会进入 Mailexam，而非真实收件人。为便于测试统一，建议使用 *.test 域名或 @example.com。

备选端口¶

587 + TLS（推荐）2525（若 25 端口被封锁）25，无加密

MAIL_PORT=587
MAIL_ENCRYPTION=tls

MAIL_PORT=2525
MAIL_ENCRYPTION=tls

MAIL_PORT=25
MAIL_ENCRYPTION=null

应用配置：

php artisan config:clear

生产环境验证通过后可缓存：php artisan config:cache。

2. 检查 `config/mail.php`¶

标准 Laravel 安装中，config/mail.php 已从 .env 读取变量，通常无需额外修改。请确认 smtp 邮件驱动使用 env('MAIL_HOST')、env('MAIL_PORT') 等。

3. 发送测试邮件¶

通过 Tinker¶

php artisan tinker

use Illuminate\Support\Facades\Mail;

Mail::raw('来自 Laravel 的 Mailexam 测试', function ($message) {
    $message->to('user@example.test')
        ->subject('Laravel + Mailexam');
});

通过 Mailable¶

php artisan make:mail WelcomeTestMail

// app/Mail/WelcomeTestMail.php
namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class WelcomeTestMail extends Mailable
{
    use Queueable, SerializesModels;

    public function envelope(): Envelope
    {
        return new Envelope(subject: '欢迎（测试）');
    }

    public function content(): Content
    {
        return new Content(view: 'emails.welcome-test');
    }
}

use App\Mail\WelcomeTestMail;
use Illuminate\Support\Facades\Mail;

Mail::to('user@example.test')->send(new WelcomeTestMail());

打开 Mailexam 控制台 → 项目 → 收件箱：数秒内应能看到该邮件。

4. 本地开发与 CI¶

环境	建议
`local`	每位开发者独立的 Mailexam 项目，或团队共享测试项目
`staging`	独立的 Mailexam 项目，通过 CI 密钥注入相同 `.env`
PHPUnit	集成测试使用真实 Mailexam SMTP，或单元测试使用 `MAIL_MAILER=array` / `log` 避免网络

GitLab CI 变量示例（Settings → CI/CD → Variables）：

variables:
  MAIL_MAILER: smtp
  MAIL_HOST: "${MAILEXAM_LOGIN}.mailexam.cn"
  MAIL_PORT: "587"
  MAIL_USERNAME: "${MAILEXAM_LOGIN}"
  MAIL_PASSWORD: "${MAILEXAM_PASSWORD}"
  MAIL_ENCRYPTION: tls

流水线发送邮件后，通过 Mailexam API 验证投递。

5. 常见问题¶

无法建立连接

MAIL_HOST 必须为 YOUR_LOGIN.mailexam.cn——与 MAIL_USERNAME 中的登录名相同，不要加 smtp. 前缀。
登录名和密码须从邮件中成对取用；勿混用其他项目的凭据。
修改 .env 后执行 php artisan config:clear。

控制台中看不到邮件

确认查看的是与 .env 中凭据对应的 Mailexam 项目收件箱。
确认发送未进入出错队列：运行 php artisan queue:work 并查看 storage/logs/laravel.log。

SSL/TLS 错误

587 端口使用 MAIL_ENCRYPTION=tls，而非 ssl。
465 端口配合 ssl 可用，但新集成不推荐使用。