Wagtail 6.1升级中的迁移冲突问题分析与解决方案

问题背景

在将项目升级到Wagtail 6.1版本时，部分开发者遇到了迁移冲突问题。具体表现为执行makemigrations命令时，系统提示存在两个冲突的迁移节点：0092_query_searchpromotion_querydailyhits和0093_uploadedfile。虽然系统建议的--merge方案可以临时解决问题，但这并非根本解决方案。

问题根源分析

该问题的核心在于：

1. 错误的模型归属：项目中引用了wagtail.contrib.search_promotions中的模型（如Query、SearchPromotion等），但未将该应用添加到INSTALLED_APPS中
2. 迁移生成机制：在Wagtail 6.0环境下，Django错误地将这些模型识别为属于wagtailcore应用，从而生成了错误的迁移文件0092_query_searchpromotion_querydailyhits
3. 版本升级冲突：升级到Wagtail 6.1后，系统检测到两个独立的迁移分支，导致冲突

完整解决方案

推荐解决步骤

1. 数据库备份：首先确保数据库已备份，以防数据丢失
2. 修正迁移依赖：
   • 在项目所有迁移文件中，将('wagtailcore', '0092_query_searchpromotion_querydailyhits')替换为('wagtailcore', '0091_remove_revision_submitted_for_moderation')
3. 回滚迁移：执行./manage.py migrate wagtailcore 0091回退到正确状态
4. 添加必要应用：在INSTALLED_APPS中添加wagtail.contrib.search_promotions
5. 清理错误迁移：
   • 删除wagtail/migrations/0092_query_searchpromotion_querydailyhits.py
   • 或重新安装Wagtail包（确保版本一致）
6. 重新应用迁移：执行./manage.py migrate完成最终迁移

注意事项

1. 对于全新项目或可丢弃的环境，可以考虑直接重建数据库
2. 确保所有团队成员都执行相同的迁移修正操作
3. 在CI/CD流程中也需要同步这些变更

最佳实践建议

1. 应用配置检查：在引用任何Wagtail子模块模型前，确保对应应用已添加到INSTALLED_APPS
2. 迁移审查：在升级Wagtail版本前，检查现有迁移文件的合理性
3. 环境隔离：建议在虚拟环境中进行升级测试
4. 版本过渡：对于大型项目，建议先升级到中间版本再升级到目标版本

技术原理

该问题揭示了Django迁移系统的一个重要特性：当模型被引用但所属应用未注册时，Django会将这些模型归属于第一个找到的已注册应用。在Wagtail中，这通常会导致模型被错误地归属到wagtailcore应用，从而产生后续的迁移冲突。

通过理解这一机制，开发者可以更好地预防和解决类似的迁移问题，确保项目的数据库结构保持健康状态。