Laravel Mailable 如何为 InvoiceEmail 邮件类添加PDF附件

Laravel的Mailable类内置了attach()方法支持本地文件附件挂载，你只需要在现有代码基础上透传PDF文件路径，在构建邮件消息时调用attach方法即可，不需要改动已有的视图渲染、主题设置逻辑。

最小改动适配现有代码结构 #

整个改造只需要两步，完全兼容你当前已经写好的业务逻辑和Mailable结构：

1. 在业务调用逻辑中补充附件路径参数
   把PDF的绝对路径、展示文件名一并放入传入Mailable的$data数组中，同时替换原来容易出错的相对路径写法，改用Laravel内置的路径辅助函数生成稳定可解析的绝对路径：

   /* Attachment File */
   $filename = "invoice".$request->id.$language.".pdf";
   // 替换原相对路径，生成storage目录下的绝对路径，避免跨环境解析错误
   $file = storage_path('app/pdf/' . $filename);
   
   // 可选：增加文件存在性校验，避免附件读取失败导致邮件发送中断
   if (!file_exists($file)) {
       // 按照项目现有错误处理逻辑抛出异常/记录日志即可
       throw new \RuntimeException("Invoice PDF file missing: " . $file);
   }
   
   $data = [
       'subject' => $subject,
       'body'    => $body,
       // 新增附件相关配置
       'pdf_path' => $file,
       'pdf_display_name' => $filename
   ];
   
   Mail::to($mail_to)->send(new InvoiceEmail($data));
   

2. 在Mailable的build方法中挂载附件
   在原有链式调用的最后增加attach()方法即可，原有视图绑定、主题设置的代码完全不需要修改：

   /**
    * Build the message.
    *
    * @return $this
    */
   public function build()
   {
       return $this->view('mail.invoice')
                   ->with('body',$this->data['body'])
                   ->subject($this->data['subject'])
                   // 新增PDF附件挂载逻辑
                   ->attach(
                       $this->data['pdf_path'],
                       [
                           'as' => $this->data['pdf_display_name'],
                           'mime' => 'application/pdf'
                       ]
                   );
   }
   

关键参数说明 #

• attach()方法的第一个参数是PDF文件在服务器上的绝对路径，Laravel会直接读取该路径的文件作为附件内容
• 第二个配置数组中：
  • as 用来指定收件人在邮件客户端看到的附件文件名，不需要和服务器上的存储文件名完全一致
  • mime 指定附件的MIME类型，能保证各类邮件客户端正确识别PDF格式，不会出现格式错乱、无法预览的问题

常见避坑提示 #

• 不要直接把相对路径（比如你原来写的core/storage/app/pdf/xxx.pdf）传给attach()，这类相对路径会根据脚本的运行工作目录解析，在CLI、Web服务、队列任务等不同运行场景下很容易出现路径不匹配、文件找不到的报错，统一使用storage_path()、public_path()这类Laravel提供的路径辅助函数生成绝对路径是最稳妥的写法
• 如果后续需要把邮件发送任务放到队列中异步执行，这套附件挂载逻辑可以直接兼容，不需要做额外改造

内容的提问来源于stack exchange，提问作者B L Praveen