告别邮件调试噩梦：Laravel Mail Preview 插件实战指南-优快云博客

告别邮件调试噩梦：Laravel Mail Preview 插件实战指南

【免费下载链接】laravel-mail-preview A mail driver to quickly preview mail 项目地址: https://gitcode.com/gh_mirrors/la/laravel-mail-preview

你是否还在为 Laravel 邮件调试抓狂？反复发送测试邮件到真实邮箱，等待服务器响应，再检查邮件格式和内容——这个过程不仅低效，还可能污染用户数据。现在，有了 Laravel Mail Preview（邮件预览插件），你可以在本地环境中即时查看邮件效果，无需发送真实邮件，开发效率提升 10 倍！

读完本文，你将掌握：

5 分钟快速搭建邮件预览环境
3 种预览模式满足不同调试场景
10+ 高级配置项自定义预览行为
单元测试中邮件内容断言技巧
生产环境安全隔离最佳实践

为什么选择 Laravel Mail Preview？

传统邮件开发流程存在三大痛点：

痛点	传统方案	Mail Preview 方案
发送延迟	依赖 SMTP 服务器响应（3-10 秒/封）	本地文件存储（毫秒级响应）
内容验证	需登录邮箱查看	浏览器即时预览
测试污染	可能发送到真实用户邮箱	完全隔离的本地存储

Laravel Mail Preview 由知名开源团队 Spatie 维护，基于 Mohamed Said 最初开发的版本重构，目前已成为 Laravel 生态中最受欢迎的邮件调试工具之一。

核心工作原理

该插件通过拦截邮件发送流程，将邮件内容保存为 HTML 和 EML 格式文件，并提供便捷的预览界面。其工作流程如下：

mermaid

快速开始：5 分钟安装配置

环境要求

Laravel 8.0+（推荐 Laravel 10 LTS）
PHP 7.4+
Composer 2.0+

1. 安装依赖包

composer require spatie/laravel-mail-preview --dev

⚠️ 注意：使用 --dev 参数仅在开发环境安装，避免影响生产环境。

2. 配置邮件驱动

修改 config/mail.php 文件，将默认邮件驱动改为 preview：

// config/mail.php
'mailers' => [
    'smtp' => [
        'transport' => env('MAIL_TRANSPORT', 'preview'), // 改为 preview
        // 其他配置保持不变
    ],
],

为避免生产环境误配置，建议在 .env 文件中添加：

# .env
MAIL_TRANSPORT=preview

3. 注册中间件和路由

编辑 app/Http/Kernel.php，将预览中间件添加到 web 中间件组：

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // 其他中间件...
        \Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class,
    ],
];

在 routes/web.php 中注册预览路由：

// routes/web.php
Route::mailPreview(); // 默认路径: /spatie-mail-preview

如需自定义路径，可传入参数：

Route::mailPreview('mail/preview'); // 自定义路径: /mail/preview

4. 验证安装结果

创建测试路由发送邮件：

// routes/web.php
Route::get('/test-mail', function () {
    \Illuminate\Support\Facades\Mail::raw('Hello Mail Preview!', function ($message) {
        $message->to('test@example.com')->subject('测试邮件');
    });
    return '邮件已发送，查看页面底部预览链接';
});

访问 /test-mail，页面底部将出现悬浮预览窗：

┌─────────────────────────────┐
│ 📧 邮件已保存 - 点击查看 →   │
└─────────────────────────────┘

点击链接即可在浏览器中查看邮件内容。

高级配置：定制你的预览体验

配置文件详解

发布配置文件：

php artisan vendor:publish --provider="Spatie\MailPreview\MailPreviewServiceProvider" --tag="mail-preview-config"

生成的 config/mail-preview.php 文件包含以下关键配置：

return [
    /*
     * 是否启用预览功能（默认跟随 APP_DEBUG）
     */
    'enabled' => env('APP_DEBUG', false),

    /*
     * 邮件存储目录（默认 storage/email-previews）
     */
    'storage_path' => storage_path('email-previews'),

    /*
     * 预览文件保留时间（秒）
     */
    'maximum_lifetime_in_seconds' => 60,

    /*
     * 是否显示预览悬浮窗
     */
    'show_link_to_preview' => true,

    /*
     * 悬浮窗自动关闭时间（秒，false 为不关闭）
     */
    'popup_timeout_in_seconds' => 8,

    /*
     * 文件名日期格式（默认微秒级，确保唯一性）
     */
    'filename_date_format' => 'u',
];

常用配置场景

场景 1：延长预览文件保存时间

开发复杂邮件模板时，可延长文件保留时间：

// config/mail-preview.php
'maximum_lifetime_in_seconds' => 3600, // 保留 1 小时

场景 2：禁用悬浮窗，手动访问预览页

在 API 开发或不需要即时预览时：

// config/mail-preview.php
'show_link_to_preview' => false,

手动访问 http://your-app.test/spatie-mail-preview 查看所有邮件列表。

场景 3：自定义存储路径

如需将邮件保存到项目外目录：

// config/mail-preview.php
'storage_path' => '/tmp/laravel-mails', // 绝对路径

三种预览模式深度解析

1. 悬浮窗预览（默认）

当 show_link_to_preview=true 时，邮件发送后会在页面底部显示悬浮窗：

<!-- 生成的悬浮窗 HTML -->
<div class="mail-preview-overlay">
    <a href="/spatie-mail-preview/1620000000_test_at_example_com_subject.html">
        📧 查看刚刚发送的邮件
    </a>
</div>

悬浮窗默认 8 秒后自动消失，可通过 popup_timeout_in_seconds 调整。

2. 邮件列表页预览

访问注册的预览路由（如 /spatie-mail-preview），将显示所有已保存的邮件列表：

邮件预览列表 (共 3 封)
=========================================
[1] 2023-05-01 10:30:00 - test@example.com - 测试邮件
[2] 2023-05-01 10:32:15 - user@example.com - 订单确认
[3] 2023-05-01 10:35:42 - admin@example.com - 系统通知
=========================================

3. 直接查看文件

邮件文件保存在 storage/email-previews 目录，文件名格式为：

{时间戳}_{收件人邮箱}_{主题}.html
{时间戳}_{收件人邮箱}_{主题}.eml

例如：1620000000_john_at_example_com_welcome.html

HTML 文件：可直接在浏览器中打开
EML 文件：可在邮件客户端（如 Outlook、Thunderbird）中打开，查看真实邮件渲染效果

单元测试：断言邮件内容

Laravel Mail Preview 提供了强大的测试断言工具，解决了原生 Mail::fake() 无法验证邮件内容的问题。

基本断言示例

use Spatie\MailPreview\Facades\SentMails;

public function test_welcome_email_contains_user_name()
{
    // 执行发送邮件的操作
    $this->post('/register', [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'password' => 'password',
    ]);
    
    // 断言最后一封邮件包含用户名
    SentMails::assertLastContains('John Doe');
    
    // 断言共发送了 1 封邮件
    SentMails::assertCount(1);
}

高级断言方法

1. 主题和收件人验证

SentMails::assertSent(function ($mail) {
    return $mail->subjectContains('欢迎注册') && 
           $mail->hasTo('john@example.com') &&
           $mail->hasCc('admin@example.com');
});

2. 邮件内容多条件验证

SentMails::assertSent(function ($mail) {
    return $mail->bodyContains('您的账号已激活') &&
           $mail->bodyContains('点击以下链接完成验证') &&
           $mail->hasBcc('audit@example.com');
}, 1); // 断言满足条件的邮件发送了 1 次

3. 完整断言方法列表

方法	描述
`assertCount(int $count)`	断言发送了指定数量的邮件
`assertLastContains(string $text)`	断言最后一封邮件包含指定文本
`assertSent(Closure $callback, int $count=1)`	断言满足条件的邮件发送了指定次数
`assertNotSent(Closure $callback)`	断言满足条件的邮件未发送
`assertNothingSent()`	断言未发送任何邮件

测试邮件示例类

SentMail 类提供以下方法获取邮件信息：

$mail = SentMails::last();
$mail->subject();      // 获取邮件主题
$mail->body();         // 获取邮件内容
$mail->to();           // 获取收件人列表
$mail->cc();           // 获取抄送列表
$mail->bcc();          // 获取密送列表
$mail->from();         // 获取发件人信息

生产环境安全配置

防止生产环境启用预览功能

尽管插件默认只在 APP_DEBUG=true 时启用，但建议通过以下措施进一步隔离：

在 config/mail.php 中添加环境判断：

// config/mail.php
'transport' => env('APP_ENV') === 'production' ? 'smtp' : 'preview',

在生产环境 .env 文件强制使用 SMTP：

# .env.production
MAIL_TRANSPORT=smtp

中间件安全加固：

编辑 app/Http/Kernel.php，仅在非生产环境注册中间件：

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // 其他中间件...
        (env('APP_ENV') !== 'production') 
            ? \Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class
            : null,
    ],
];

常见问题与解决方案

Q1: 预览悬浮窗不显示怎么办？

排查步骤：

确认 APP_DEBUG=true
检查 config/mail-preview.php 中 enabled=true 和 show_link_to_preview=true
确认中间件已添加到 web 中间件组
查看浏览器控制台是否有 JavaScript 错误
检查响应页面是否包含 </body> 标签（悬浮窗需注入到 </body> 之前）

Q2: 邮件文件保存在哪里？

默认存储路径：storage/email-previews，可通过 config/mail-preview.php 中的 storage_path 配置修改。

Q3: 如何自定义预览悬浮窗样式？

发布视图文件进行自定义：

php artisan vendor:publish --provider="Spatie\MailPreview\MailPreviewServiceProvider" --tag="mail-preview-views"

修改生成的视图文件：resources/views/vendor/mail-preview/previewLinkPopup.blade.php

Q4: 能否在 CLI 命令中使用预览功能？

可以，但需要手动访问预览页面。发送邮件后，可通过以下命令查看存储的邮件文件：

ls -l storage/email-previews/

然后在浏览器中访问 http://your-app.test/spatie-mail-preview/filename.html 查看。

性能优化与最佳实践

1. 限制邮件存储时间

开发环境长期运行可能导致邮件文件堆积，建议设置合理的保留时间：

// config/mail-preview.php
'maximum_lifetime_in_seconds' => 3600, // 1 小时

2. 集成到开发工作流

在 phpunit.xml 中添加测试前置操作，自动清理测试邮件：

<phpunit>
    <testsuites>
        <!-- 测试套件配置 -->
    </testsuites>
    <php>
        <env name="MAIL_TRANSPORT" value="preview"/>
    </php>
    <listeners>
        <listener class="Spatie\MailPreview\Testing\CleanupMailsListener"/>
    </listeners>
</phpunit>

3. 版本控制忽略邮件存储目录

在 .gitignore 中添加：

/storage/email-previews/

从旧版本迁移

从 themsaid/laravel-mail-preview 迁移

卸载旧包：

composer remove themsaid/laravel-mail-preview

安装新包：

composer require spatie/laravel-mail-preview --dev

更新中间件类名（命名空间变更）：

// 旧:
\Themsaid\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class,

// 新:
\Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class,

版本升级注意事项

版本	Laravel 支持	主要变更
v1.x	5.5-7.x	初始版本
v2.x	8.x-9.x	支持 Laravel 8+，重构内部架构
v3.x	10.x+	支持 PHP 8.1+，移除旧版兼容代码

升级到 v3.x 需注意：

移除了 MailPreview::routes() 方法，统一使用 Route::mailPreview()
SentMails 门面命名空间从 Spatie\MailPreview\SentMails 改为 Spatie\MailPreview\Facades\SentMails

总结与展望

Laravel Mail Preview 彻底改变了 Laravel 邮件开发流程，通过本地文件存储和即时预览，将邮件调试效率提升了一个数量级。其核心优势包括：

开发效率：毫秒级邮件预览，无需等待 SMTP 服务器响应
内容验证：浏览器和邮件客户端双重验证邮件渲染效果
测试能力：强大的断言工具确保邮件内容正确性
安全隔离：生产环境自动禁用，避免测试邮件发送到真实用户

未来版本可能加入的功能：

邮件内容对比工具
响应式邮件预览（移动端视图模拟）
邮件模板调试工具栏

告别邮件调试噩梦：Laravel Mail Preview 插件实战指南