本文介绍如何利用 laravel excel 的自定义验证机制，在导入前实时检测 excel 文件中指定列（如 email）是否存在重复值，并中断导入、返回清晰错误提示，避免无效数据处理。

本文介绍如何利用 laravel excel 的自定义验证机制，在导入前实时检测 excel 文件中指定列（如 email）是否存在重复值，并中断导入、返回清晰错误提示，避免无效数据处理。

在使用 Laravel Excel（maatwebsite/excel）进行批量导入时，若业务逻辑要求某列（例如 email、employee_id 或 phone）必须唯一，但又不涉及数据库唯一性校验（如你当前仅执行更新操作、未插入新记录，且 Rule::unique() 无法生效），则需在内存中对 Excel 行数据进行去重校验——此时 Laravel 内置的 distinct 验证规则正是理想选择。

distinct 规则专为集合（Collection）级去重设计，它会在当前导入批次（chunk）内检查字段值是否重复，完全脱离数据库，完美适配你的 Collection 导入模式（配合 batchSize() / chunkSize()）。

✅ 正确实现方式

在你的 Import 类中，重写 rules() 方法，为需校验的列添加 'distinct' 规则：

<?php namespace App\Imports;

use Maatwebsite\Excel\Concerns\ToCollection;
use Maatwebsite\Excel\Concerns\WithValidation;
use Illuminate\Support\Collection;
use PhpOffice\PhpSpreadsheet\Shared\Date;

class EmployeeUpdateImport implements ToCollection, WithValidation
{
    public function collection(Collection $rows)
    {
        // 此处执行你的更新逻辑，例如：
        // $rows->each(function ($row) {
        //     Employee::updateOrCreate(
        //         ['email' => $row['email']],
        //         ['name' => $row['name'], 'department' => $row['department']]
        //     );
        // });
    }

    public function rules(): array
    {
        return [
            'email' => 'required|string|distinct',
            // 可选：限制长度或格式
            // 'email' => 'required|email|string|distinct',
        ];
    }
}

⚠️ 注意事项：

• distinct 默认区分大小写。如需忽略大小写（如 user@EXAMPLE.COM 和 user@example.com 视为重复），请改用自定义闭包验证：

  'email' => [
      'required',
      'string',
      function ($attribute, $value, $fail) use ($rows) {
          $emails = $rows->pluck($attribute)->map(fn($e) => strtolower($e));
          if ($emails->duplicates()->isNotEmpty()) {
              $fail("Column '{$attribute}' contains duplicate values (case-insensitive).");
          }
      }
  ]

• distinct 作用于当前 chunk（即每次 chunkSize() 处理的数据块），而非整个文件。若需全文件级去重（跨 chunk 检测），需自行缓存已见值（例如用 static $seen = [] 或 Redis），但会增加内存开销，应谨慎评估必要性。
• 错误将自动捕获并抛出 ValidationException，Laravel Excel 会中止导入，并可通过 $import->failures() 获取详细错误行与列信息，便于前端精准提示用户：“第3行与第12行 email 重复，请修正后重传”。

? 补充：结合导入控制器返回友好响应

// 在 Controller 中
use Maatwebsite\Excel\Validators\ValidationException;

try {
    Excel::import(new EmployeeUpdateImport, $request->file('excel'));
    return response()->json(['message' => '导入成功，所有记录已更新。']);
} catch (ValidationException $e) {
    $failures = $e->failures();
    $errors = collect($failures)->mapWithKeys(function ($failure) {
        return [$failure->row() => $failure->errors()];
    })->all();

    return response()->json([
        'message' => '导入失败：检测到重复值，请检查 Excel 文件。',
        'errors' => $errors
    ], 422);
}

通过以上配置，你无需修改数据库结构或引入额外服务，即可在 Laravel Excel 导入链路最前端实现轻量、可靠、可维护的列级重复值拦截，显著提升数据质量与用户体验。