如何在 Laravel Excel 导入时校验并阻止重复列值-php教程-PHP中文网

如何在 Laravel Excel 导入时校验并阻止重复列值

本文介绍如何利用 laravel excel 的自定义导入规则，在数据入库前实时检测 excel 文件中指定列（如 email）是否存在重复值，并中断导入流程、向用户返回清晰错误提示。

本文介绍如何利用 laravel excel 的自定义导入规则，在数据入库前实时检测 excel 文件中指定列（如 email）是否存在重复值，并中断导入流程、向用户返回清晰错误提示。

在使用 Laravel Excel（如 maatwebsite/excel）进行批量导入时，若业务逻辑要求某列（例如 email、employee_id 或 phone）必须全局唯一（即 Excel 文件内部不能出现重复），仅依赖数据库层的 unique 规则（如 Rule::unique('employees', 'email')）是无效的——因为该规则校验的是数据库已有记录，而非当前上传文件内各行之间的重复。

此时应使用 Laravel 原生提供的 distinct 验证规则，它专为「同一导入批次内字段值互异」场景设计，完美契合你的需求：在 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 EmployeeImport implements ToCollection, WithValidation
{
    public function collection(Collection $rows)
    {
        // 此处处理数据：遍历 $rows，根据条件更新员工记录（非插入）
        foreach ($rows as $row) {
            // 示例：根据 email 查找并更新员工
            \App\Models\Employee::updateOrCreate(
                ['email' => $row['email']],
                [
                    'name' => $row['name'],
                    'department' => $row['department'],
                    'updated_at' => now(),
                ]
            );
        }
    }

    public function rules(): array
    {
        return [
            'email' => 'required|string|email|distinct',
            // 可扩展其他列，如：
            // 'employee_id' => 'required|string|distinct',
        ];
    }

    // （可选）自定义错误消息提升用户体验
    public function customValidationMessages(): array
    {
        return [
            'email.distinct' => 'Excel 文件中存在重复的邮箱地址，请检查后重新上传。',
        ];
    }
}

⚠️ 关键注意事项

distinct 作用域仅限当前导入批次：它对比的是本次上传 Excel 中所有已解析行的该字段值，不查询数据库，因此无需额外配置表名或字段名。
必须启用验证契约：确保类同时实现了 WithValidation 接口，否则 rules() 方法不会被调用。
与 batchSize() 兼容：distinct 在每个 batch 内独立校验（即分块内去重），若需跨 batch 全局去重（极少见），需自行缓存已处理值并手动校验。
字段名需匹配 Excel 表头：确保 rules() 中的键（如 'email'）与 Excel 文件首行（header row）的列名完全一致（大小写敏感）；若使用 HeadingRow 自定义，需同步调整。
错误处理建议：在控制器中捕获 ValidationException 并返回结构化响应，例如：

use Illuminate\Validation\ValidationException;

try {
    Excel::import(new EmployeeImport, $request->file('excel'));
    return response()->json(['message' => '导入成功']);
} catch (ValidationException $e) {
    return response()->json([
        'message' => '导入失败',
        'errors' => $e->errors()
    ], 422);
}