本文详解如何使用 Laravel Excel（Maatwebsite/Excel）导出含关联模型（如 Attendance 关联 User）的 Excel 表格，通过 with() 预加载 + map() 方法优雅拼接关系字段，避免 N+1 查询，实现类似 SQL JOIN 的效果。
本文详解如何使用 laravel excel（maatwebsite/excel）导出含关联模型（如 attendance 关联 user）的 excel 表格，通过 `with()` 预加载 + `map()` 方法优雅拼接关系字段，避免 n+1 查询，实现类似 sql join 的效果。
在 Laravel 中使用 Maatwebsite/Laravel-Excel 导出数据时，若仅调用 Attendance::all()，默认只会导出 attendances 表的原始字段，无法显示关联的用户姓名（users.name）或状态中文描述（如 'Check In'/'Check Out'）。要实现类似原生 SQL JOIN 的效果（如 SELECT ... FROM attendances INNER JOIN users ON ...），关键在于预加载关联关系并在导出映射阶段手动组装字段，而非依赖原始查询。
✅ 正确做法：预加载 + 映射转换
首先，确保 Attendance 模型正确定义了与 User 的关联关系：
// app/Models/Attendance.php
public function user()
{
return $this->belongsTo(User::class, 'user_id'); // 显式指定外键（可选，默认为 user_id）
}
接着，在 Excel 导出类（如 AttendanceExport）中，必须使用 with('user') 预加载，否则 $row->user 会触发延迟加载（N+1 问题），极大降低性能：
// app/Exports/AttendanceExport.php
<?php namespace App\Exports;
use App\Models\Attendance;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;
use Maatwebsite\Excel\Concerns\WithMapping;
class AttendanceExport implements FromCollection, WithHeadings, WithMapping
{
public function collection()
{
// ✅ 关键：预加载 user 关系，避免循环中多次查询
return Attendance::with('user')->get();
}
public function map($attendance): array
{
// ✅ 将 status 数字转为可读文本，并安全访问关联模型（防止空用户）
$statusText = $attendance->status == 0 ? 'Check In' : 'Check Out';
$userName = $attendance->user?->name ?? 'Unknown';
return [
$attendance->id,
$userName,
$statusText,
$attendance->created_at,
$attendance->updated_at,
];
}
public function headings(): array
{
return [
'ID',
'User Name',
'Status',
'Created At',
'Updated At',
];
}
}
? 为什么不用 Attendance::all()？
Attendance::all() 不支持关联预加载；而 Attendance::with('user')->get() 会在单次查询中获取所有 attendance 记录，并额外执行 1 次 JOIN 查询 获取全部关联用户，效率远高于在 map() 中逐条访问 $attendance->user（那将触发 N 次独立查询）。
? 常见错误规避
- ❌ 错误：在 collection() 中直接写 Attendance::all()，再于 map() 中访问 $row->user->name → 触发 N+1 查询，导出慢且易超时。
- ❌ 错误：未处理关联模型为空（如 user_id 为 null 或用户被删除）→ $row->user->name 报 Trying to get property 'name' of non-object。应使用空合并操作符：$row->user?->name ?? 'N/A'。
- ❌ 错误：忽略时区或格式化 → created_at 默认导出为 Carbon 实例，Excel 可能显示为时间戳。如需标准格式，可在 map() 中处理：$attendance->created_at->format('Y-m-d H:i:s')。
✅ 进阶：自定义列标题与样式（可选）
可通过 registerEvents() 添加样式，例如自动调整列宽、设置表头背景色：
use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
use Maatwebsite\Excel\Concerns\ShouldAutoSize;
use Maatwebsite\Excel\Concerns\WithEvents;
use Maatwebsite\Excel\Events\AfterSheet;
class AttendanceExport implements FromCollection, WithHeadings, WithMapping, WithEvents, ShouldAutoSize
{
// ... 其他方法保持不变
public function registerEvents(): array
{
return [
AfterSheet::class => function(AfterSheet $event) {
$sheet = $event->sheet->getDelegate();
// 设置第一行（表头）加粗 & 背景色
$sheet->getStyle('A1:E1')->applyFromArray([
'font' => ['bold' => true],
'fill' => [
'fillType' => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID,
'startColor' => ['argb' => 'FF4CAF50'],
],
]);
// 自动列宽（由 ShouldAutoSize 支持）
},
];
}
}
? 总结
Laravel Excel 导出关联数据的核心逻辑是：
1️⃣ 在 collection() 中用 with('relation') 预加载关联模型；
2️⃣ 在 map() 中安全访问关联属性（配合空值判断），并完成字段转换（如状态映射）；
3️⃣ 在 headings() 中对齐列名，确保语义清晰；
4️⃣ 必要时通过 WithEvents 增强导出体验。
这种方式完全替代了手写原生 SQL JOIN，既符合 Laravel 的 Eloquent 风格，又保障性能与可维护性。
