laravel 迁移中为 email 字段添加 `->unique()` 时出现 “connection refused” 错误，实际根源常是数据库连接异常或字段类型与索引限制不兼容；本文详解排查逻辑、根本原因（如 mariadb 10.4+ 对 text 字段 unique 索引的支持差异）及安全可靠的解决方案。
在 Laravel 中为 email 字段添加唯一约束看似简单——只需在迁移文件中写 $table->string('email', 80)->unique()，但执行 php artisan migrate 时却报错：
SQLSTATE[HY000] [2002] Connection refused (SQL: alter table `users` add unique `users_email_unique`(`email`))
⚠️ 注意：该错误 并非 源于 unique() 语法本身，也不是 Schema::defaultStringLength(191) 配置失效——而是典型的数据库连接层异常伪装成 SQL 语法错误。Connection refused 明确指向 MySQL/MariaDB 服务未运行、端口不通、认证失败或配置错误（如 .env 中 DB_HOST、DB_PORT、DB_USERNAME/DB_PASSWORD 不正确），而非索引长度问题。
✅ 正确排查顺序如下：
-
验证数据库服务状态
# Linux/macOS sudo systemctl status mariadb # 或 mysql # 或尝试手动连接 mysql -h 127.0.0.1 -P 3306 -u your_user -p
-
检查 .env 数据库配置
确保以下字段准确无误（尤其 DB_HOST 不要写成 localhost —— 在某些 Docker 或 IPv6 环境下会导致解析失败，建议显式用 127.0.0.1）：DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_db_name DB_USERNAME=your_user DB_PASSWORD=your_password
修改后务必重载配置：
php artisan config:clear
-
关于 string() vs text() 与 UNIQUE 的澄清
原答案中提到“改用 $table->text('email')->unique() 解决问题”，这虽在 MariaDB 10.4+ 中可行，但不推荐作为常规方案：- TEXT 类型不支持默认值、部分索引优化，且 Laravel 的 Auth 系统和 User 模型约定 email 为 VARCHAR；
- 真正的索引长度限制（如 InnoDB 对 VARCHAR 索引前缀长度限制为 767 字节，utf8mb4 下约 191 字符）应通过 Schema::defaultStringLength(191) + string('email', 191)->unique() 解决，而非降级为 TEXT。
✅ 推荐的健壮写法（兼容 MySQL 5.7+/MariaDB 10.2+）：
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;
return new class extends Migration {
public function up(Blueprint $table) {
Schema::create('users', function (Blueprint $table) {
$table->id();
$table->string('company')->nullable();
$table->string('street', 80)->nullable();
$table->string('zip', 10)->nullable();
$table->string('city', 80)->nullable();
$table->string('country', 3)->nullable();
$table->string('firstname', 80)->nullable();
$table->string('lastname', 80)->nullable();
$table->string('email', 191)->unique(); // ✅ 显式设为 191，匹配 defaultStringLength
$table->timestamp('email_verified_at')->nullable();
$table->string('password');
$table->timestamps();
});
}
};并在 AppServiceProvider::boot() 中确保：
use Illuminate\Support\Facades\Schema;
public function boot()
{
Schema::defaultStringLength(191); // 必须在 boot() 中调用
}? 总结：
- Connection refused 是网络/配置层错误，优先排查数据库服务与 .env；
- ->unique() 本身无需 text() 曲线救国，标准 string(191)->unique() 即可满足索引要求；
- 避免在生产迁移中随意切换字段类型（如 string → text），以防 ORM 行为异常或后续 WHERE 查询性能下降。
修复连接问题后，迁移将顺利执行，并在 email 字段上创建高效、符合 Laravel 最佳实践的唯一索引。
