Laravel Excel：如何将数据库表字段设置为导出表头

核心逻辑写在导出类的headings()方法里，通过构造传参控制表头模式，未指定自定义表头时直接读取对应数据表的原生字段名即可，不用额外写复杂的适配逻辑。

导出类实现代码 #

直接在对应导出类里加开关判断，以用户导出为例：

<?php

namespace App\Exports;

use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;
use App\Models\User;
use Schema;

class UsersExport implements FromCollection, WithHeadings
{
    // 控制是否启用自定义表头的开关
    protected bool $useCustomHead;

    // 预设的自定义表头映射，键对应表字段，值对应导出展示的表头名
    protected array $customHeadMap = [
        'id'         => 'ID',
        'firstname'  => 'First Name',
        'lastname'   => 'Last Name',
        'email'      => 'E-Mail',
        'created_at' => 'Date'
    ];

    public function __construct(bool $useCustomHead = true)
    {
        $this->useCustomHead = $useCustomHead;
    }

    // 查询导出数据，字段和自定义表头的键保持一致
    public function collection()
    {
        return User::select(array_keys($this->customHeadMap))->get();
    }

    // 动态生成表头，Laravel Excel 会自动调用这个方法取表头
    public function headings(): array
    {
        // 开启自定义表头时，直接返回预设的格式化表头
        if ($this->useCustomHead) {
            return array_values($this->customHeadMap);
        }

        // 关闭自定义表头时，直接读取数据表原生字段作为表头
        return Schema::getColumnListing((new User())->getTable());
    }
}

两种导出场景调用 #

• 导出自定义表头的文件：表头展示为ID、First Name、Last Name、E-Mail、Date

return Excel::download(new UsersExport(useCustomHead: true), '用户列表_自定义表头.xlsx');

• 导出原生字段表头的文件：表头直接展示id、firstname、lastname、email、created_at等数据表原生字段

return Excel::download(new UsersExport(useCustomHead: false), '用户列表_原生字段.xlsx');

可选优化 #

• 多导出类复用：把动态表头、读取表字段的逻辑抽成公共基类，所有业务导出类继承基类后，只需要定义自身的$customHeadMap和绑定的模型即可，不用重复写相同逻辑。
• 动态配置表头：如果需要让用户在后台自行配置表头，只需要把$customHeadMap的读取逻辑改成从后台配置表查询，核心的判断逻辑不需要改动。
• 字段对齐校验：可以在类初始化时加一层校验，保证查询的字段顺序和表头返回顺序完全一致，避免出现列和表头错位的问题。

踩坑提示：如果导出时只查询部分字段，记得同步过滤原生字段列表，不要返回全表字段，否则会出现表头列数和数据列数不匹配的报错。

内容的提问来源于stack exchange，提问作者ronrun