Laravel插入用户时遇不存在邮箱的重复条目错误怎么办？

问题现象 #

尝试向users表插入新用户时，抛出以下SQL异常：

SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'sahan12@gmail.com' for key 'users_email_unique'

但使用Laravel查询语句：

DB::table('users')->where('email', 'sahan12@gmail.com')->first()

查询结果返回null，数据库中看似不存在该邮箱的用户。

上下文信息 #

• 通过迁移创建users表，email字段设置了唯一约束
• 插入操作前曾使用Laravel的Seeder生成测试数据

相关代码 #

迁移代码 #

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->string('user_name')->unique()->nullable();
    $table->string('phone')->unique()->nullable();
    $table->timestamp('email_verified_at')->nullable();
    $table->string('password');
    $table->rememberToken();
    $table->enum('role', ['student', 'teacher', 'admin']);
    $table->boolean('is_active')->default(1);
    $table->timestamps();
    $table->softDeletes();
});

验证规则代码 #

public function rules(): array
{
    $rules = [
        'user_name' => [
            'nullable',
            'string',
            Rule::unique('users', 'user_name'),
        ],
        'email' => [
            'required',
            'email',
            Rule::unique('users', 'email'),
        ],
    ];

    return $rules;
}

疑问 #

1. 为什么Laravel/MySQL会针对不存在的邮箱抛出该错误？
2. 如何排查并解决这个问题？

原因分析与解决方案 #

1. 原因解析 #

最常见的触发场景是软删除记录导致的冲突：

• users表启用了softDeletes，Laravel的默认查询会自动过滤deleted_at IS NOT NULL的软删除记录，所以普通查询看不到该邮箱的记录
• 但MySQL的唯一约束作用于表中所有记录（包括软删除的），如果软删除记录中存在sahan12@gmail.com，插入新数据时就会触发唯一约束冲突

其他可能原因：

• 数据库唯一索引损坏：索引与实际数据不一致，MySQL误判存在重复记录
• 大小写敏感性问题：如果email字段使用区分大小写的排序规则（如utf8_bin），可能存在大小写不同但被约束判定为重复的记录

2. 排查与解决步骤 #

步骤1：检查软删除记录

执行包含软删除记录的查询，确认是否存在目标邮箱：

// Laravel查询
DB::table('users')->withTrashed()->where('email', 'sahan12@gmail.com')->first();

或者直接用MySQL命令行查询（绕过Laravel的默认过滤）：

SELECT * FROM users WHERE email = 'sahan12@gmail.com';

步骤2：处理软删除记录

如果确实存在软删除的目标邮箱记录：

• 若业务允许忽略软删记录插入重复邮箱，修改验证规则：

  'email' => [
      'required',
      'email',
      Rule::unique('users', 'email')->whereNull('deleted_at'),
  ],
  

• 若不需要保留该软删记录，永久删除：

  DB::table('users')->withTrashed()->where('email', 'sahan12@gmail.com')->forceDelete();
  

• 若需要恢复该记录：

  DB::table('users')->withTrashed()->where('email', 'sahan12@gmail.com')->restore();
  

步骤3：修复损坏的唯一索引

如果确认数据库中没有任何目标邮箱的记录（包括软删），则可能是索引损坏，需要重建：

-- 删除原有唯一索引
ALTER TABLE users DROP INDEX users_email_unique;
-- 重新创建唯一索引
ALTER TABLE users ADD UNIQUE INDEX users_email_unique (email);

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