如何用Laravel Excel包正确导入带BOM的UTF-8格式CSV文件

问题场景 #

使用SpartnerNL/Laravel-Excel包导入CSV时出现解析异常，具体情况如下：

• 目标CSV内容：

Name,Time,Amount (ml),Note
Dave Smith,"14/08/2022, 22:18",60
Sarah Jones,"14/08/2022, 18:00",100
Mark Brown,"14/08/2022, 13:54",100

• 导入类的model方法：

public function model(array $row)
{
    dd($row);
}

• 异常解析结果：

array:3 [
  0 => "Name,Time,Amount"
  1 => "(ml),Note"
  2 => null
]

• 文件编码：通过终端确认是Unicode text, UTF-8 (with BOM) text，尝试修改input_encoding为UTF-8、设置use_bom=true均无效，且无法修改源文件格式。

可行解决方法 #

方法1：在导入类中通过onReading预处理移除BOM #

利用Laravel-Excel的WithReadings接口，在读取文件时动态移除BOM头：

use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;
use Maatwebsite\Excel\Concerns\WithReadings;

class YourImport implements ToModel, WithCustomCsvSettings, WithReadings
{
    public function model(array $row)
    {
        // 此处编写正常的行处理逻辑
        dd($row);
    }

    public function getCsvSettings(): array
    {
        return [
            'delimiter' => ',',
            'input_encoding' => 'UTF-8',
        ];
    }

    public function onReading(\Maatwebsite\Excel\Readers\CsvReader $reader)
    {
        // 移除UTF-8 BOM头
        $reader->getStreamFilter()->add(function ($content) {
            return preg_replace('/^\xEF\xBB\xBF/', '', $content);
        });
    }
}

方法2：手动预处理文件内容后导入 #

先读取文件并移除BOM，再写入临时文件供Laravel-Excel导入：

// 源文件路径
$filePath = storage_path('app/my_file.csv');
// 读取内容并移除BOM
$content = file_get_contents($filePath);
$content = preg_replace('/^\xEF\xBB\xBF/', '', $content);

// 创建临时文件
$tempFile = tempnam(sys_get_temp_dir(), 'processed_csv_');
file_put_contents($tempFile, $content);

// 执行导入
Excel::import(new YourImport, $tempFile);

// 清理临时文件
unlink($tempFile);

方法3：调整CSV阅读器配置（结合预处理） #

如果单纯设置use_bom无效，可在自定义CSV设置中保留相关配置，同时配合上述预处理逻辑：

public function getCsvSettings(): array
{
    return [
        'delimiter' => ',',
        'input_encoding' => 'UTF-8',
        'use_bom' => true,
    ];
}

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