本文探讨 laravel 8 迁移中常见的“重复列”外键错误，该错误通常源于同时使用 unsignedBigInteger 和 foreignId 定义同一列。教程将详细解释 foreignId()->constrained() 的正确用法，指出其已包含列创建逻辑，从而避免重复定义，确保数据库迁移顺利进行。通过具体代码示例，帮助开发者理解并规避此问题，提升 Laravel 数据库操作的效率与准确性。
问题解析：SQLSTATE[42S21] 错误成因
在 Laravel 数据库迁移过程中，当尝试添加外键并执行 php artisan migrate:fresh 命令时，有时会遇到 SQLSTATE[42S21]: column already exists: 1060 Duplicate column name ‘id_rso’ 这样的错误。这个错误明确指出，在尝试创建表时，某个列（例如 id_rso）被重复定义了。
根据提供的迁移代码片段：
public function up() { Schema::enableForeignKeyConstraints(); Schema::create('dso', function (Blueprint $table) { $table->string('id_dso',30); $table->unsignedBigInteger('id_rso'); // 第一次定义 $table->foreignId('id_rso')->constrained('rso'); // 第二次定义 // ... 其他列 ... }); }
问题的根源在于 id_rso 列被定义了两次：
- $table->unsignedBigInteger(‘id_rso’);：这行代码会创建一个名为 id_rso 的 UNSIGNED BIGINT 类型的列。
- $table->foreignId(‘id_rso’)->constrained(‘rso’);：foreignId() 方法是 Laravel 8 及更高版本中引入的便捷方法。它不仅会创建一个符合外键要求的 UNSIGNED BIGINT 类型的列，还会自动添加外键约束。
因此，当这两行代码同时存在时，数据库会尝试创建两次 id_rso 列，从而导致“列已存在”的错误。
foreignId 的正确使用姿势
foreignId() 方法的引入，正是为了简化外键的定义过程。它封装了创建列和添加约束的逻辑，使得代码更加简洁和语义化。
要解决上述“重复列”错误，正确的做法是只使用 foreignId()->constrained() 方法来定义外键列。此方法会智能地完成以下两步操作：
- 创建与关联表主键类型兼容的 UNSIGNED BIGINT 类型列。
- 为该列添加外键约束，指向指定表的主键。
代码示例与对比
错误的迁移代码（导致重复列错误）：
// app/database/migrations/xxxx_xx_xx_xxxxxx_create_dso_table.php use IlluminateDatabaseMigrationsMigration; use IlluminateDatabaseSchemaBlueprint; use IlluminateSupportFacadesSchema; class CreateDsoTable extends Migration { public function up() { Schema::enableForeignKeyConstraints(); // 启用外键约束，通常推荐保留 Schema::create('dso', function (Blueprint $table) { $table->string('id_dso', 30); $table->unsignedBigInteger('id_rso'); // 错误：此行不应与 foreignId 同时使用 $table->foreignId('id_rso')->constrained('rso'); // 正确：但与上一行重复 $table->smallInteger('id_focus'); $table->smallInteger('id_wilayah'); $table->smallInteger('id_grup_wilayah'); $table->string('nama_dso', 50); $table->string('created_by', 50)->nullable(); $table->timestamp('created_date', $precision = 0); $table->string('modified_by', 50)->nullable(); $table->timestamp('modified_date', $precision = 0)->nullable()->default(null); $table->boolean('status')->default(true); $table->timestamps(); // 添加 created_at 和 updated_at $table->primary('id_dso'); }); } public function down() { Schema::dropIfExists('dso'); } }
修正后的迁移代码（避免重复列错误）：
// app/database/migrations/xxxx_xx_xx_xxxxxx_create_dso_table.php use IlluminateDatabaseMigrationsMigration; use IlluminateDatabaseSchemaBlueprint; use IlluminateSupportFacadesSchema; class CreateDsoTable extends Migration { public function up() { Schema::enableForeignKeyConstraints(); // 启用外键约束，通常推荐保留 Schema::create('dso', function (Blueprint $table) { $table->string('id_dso', 30); // 只使用 foreignId() 来定义外键列，它会自动创建 UNSIGNED BIGINT 类型的列并添加约束 $table->foreignId('id_rso')->constrained('rso'); $table->smallInteger('id_focus'); $table->smallInteger('id_wilayah'); $table->smallInteger('id_grup_wilayah'); $table->string('nama_dso', 50); $table->string('created_by', 50)->nullable(); $table->timestamp('created_date', $precision = 0); $table->string('modified_by', 50)->nullable(); $table->timestamp('modified_date', $precision = 0)->nullable()->default(null); $table->boolean('status')->default(true); $table->timestamps(); // 添加 created_at 和 updated_at $table->primary('id_dso'); }); } public function down() { Schema::dropIfExists('dso'); } }
通过移除 unsignedBigInteger(‘id_rso’) 这一行，我们确保了 id_rso 列只被定义一次，从而避免了 Duplicate column name 错误。
理解 foreignId 的内部机制
foreignId() 方法是 Laravel 框架为了提高开发效率而提供的一个语法糖。它默认会生成一个名为 [column_name] 的 UNSIGNED BIGINT 类型列。当与 constrained() 方法链式调用时，它会进一步：
- 自动推断关联表的名称。如果 constrained() 没有参数，它会尝试根据列名（例如 id_rso）推断出表名（rso）。
- 将外键约束指向关联表的主键（通常是 id）。
如果你需要更精细地控制外键列的类型或约束，例如关联的不是 id 列，或者需要自定义外键名称，你仍然可以使用传统的 unsignedBigInteger()->foreign()->references()->on() 链式调用。但对于大多数标准的外键关联，foreignId()->constrained() 是最推荐和简洁的方式。
注意事项与最佳实践
- Schema::enableForeignKeyConstraints(): 在 up() 方法中调用 Schema::enableForeignKeyConstraints() 是一个好的习惯，尤其是在执行复杂迁移（如先删除表再创建，或者涉及大量外键操作）时，它可以确保外键约束在操作完成后被重新启用，避免数据不一致。虽然它不是导致本例中重复列错误的直接原因，但它是数据库迁移中的重要组成部分。
- 迁移顺序： 在定义外键时，务必确保被引用的表（例如本例中的 rso 表）的迁移文件在引用表（dso 表）的迁移文件之前运行。Laravel 会根据迁移文件名中的时间戳来决定执行顺序。
- 回滚操作： 在 down() 方法中，通常建议使用 Schema::dropIfExists(‘table_name’) 来安全地回滚迁移。对于外键，Laravel 会在删除表时自动处理其相关的外键约束。
总结
当在 Laravel 迁移中遇到“重复列”错误，尤其是在定义外键时，首先检查是否同时使用了 unsignedBigInteger() 和 foreignId() 来定义同一个列。记住，foreignId() 方法已经包含了创建 UNSIGNED BIGINT 列的逻辑，因此只需使用 foreignId()->constrained(‘关联表名’) 即可正确且简洁地定义外键。遵循这一最佳实践，将有助于避免常见的迁移错误，并使你的 Laravel 数据库操作更加顺畅和高效。
