Flutter Floor数据库升级报错：duplicate column name: kit

问题原因 #

你遇到的duplicate column name: kit错误，核心是版本6的SavedTeam实体类新增了kit字段，但该字段已经在migration4to5中手动添加到数据库表中。Floor在数据库升级时，会尝试根据实体类定义同步表结构，导致重复执行添加kit列的操作，触发冲突。

尽管你已经通过手动迁移添加了该列，但实体类新增字段后，Floor会默认尝试自动同步该字段到表中，和已存在的列产生重复。

解决方案 #

1. 对齐实体类与数据库表结构 #

确认SavedTeam实体类中的kit字段和数据库中已有的列定义完全匹配：

class SavedTeam {
  // 其他字段...
  @ColumnInfo(name: 'kit', typeAffinity: ColumnType.TEXT)
  final String? kit; // 类型要和migration4to5中添加的TEXT一致

  SavedTeam({
    // 其他参数...
    this.kit,
  });
}

2. 在迁移中添加列存在性检查 #

如果Floor仍自动尝试添加列，在migration5to6中加入检查逻辑，确保仅当列不存在时才执行添加：

final migration5to6 = Migration(5, 6, (database) async {
  // 保留原有创建KitPattern表的代码
  await database.execute('CREATE TABLE IF NOT EXISTS `KitPattern` '
      '(`id` TEXT NOT NULL, '
      ' `productId` TEXT NOT NULL, '
      ' `assetPath` TEXT NOT NULL, '
      'PRIMARY KEY (`id`))');

  // 检查SavedTeam表是否已有kit列，不存在才添加
  final tableInfo = await database.rawQuery("PRAGMA table_info(SavedTeam)");
  bool hasKitColumn = tableInfo.any((row) => row['name'] == 'kit');
  if (!hasKitColumn) {
    await database.execute('ALTER TABLE SavedTeam ADD COLUMN kit TEXT');
  }
});

3. 明确禁用Floor自动迁移 #

部分Floor版本即使添加了手动迁移，仍会默认启用自动迁移，需显式禁用：

final localDatabase = $FloorLocalDatabase
    .databaseBuilder('local_database.db')
    .addMigrations([
      migration1to2,
      migration2to3,
      migration3to4,
      migration4to5,
      migration5to6
    ])
    .disableAutoMigrations() // 禁用自动迁移，完全依赖手动迁移
    .build();

验证步骤 #

• 卸载旧版本应用，安装版本6，测试从初始版本升级是否正常
• 保留版本5的数据库，直接升级到版本6，确认错误不再出现

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