Wagtail 升级至6.2版本时自定义用户模型报错解决方案

在将Wagtail从6.1.3版本升级到6.2版本时，部分开发者遇到了关于自定义用户模型的兼容性问题。本文将详细分析该问题的成因，并提供完整的解决方案。

问题现象

当开发者尝试在Wagtail 6.2版本中使用自定义用户模型时，系统会抛出以下错误：

LookupError: App 'accounts' doesn't have a 'CustomUser' model.

或

django.core.exceptions.ImproperlyConfigured: AUTH_USER_MODEL refers to model 'accounts.CustomUser' that has not been installed

问题根源

该问题源于Wagtail 6.2版本中admin/models.py文件的实现方式。在该文件中，直接调用了get_user_model()函数来获取用户模型，这会导致在Django应用初始化阶段过早地尝试加载用户模型。

具体来说，当其他模块（如过滤器）导入wagtail.admin.models时，Django的应用注册表可能尚未完全初始化，特别是当自定义用户模型位于其他应用中时，这种时序问题就会显现。

解决方案

有两种方法可以解决这个问题：

方法一：临时修改源码

1. 找到Wagtail安装目录下的admin/models.py文件
2. 修改文件开头的导入语句：

from django.conf import settings

3. 修改用户模型引用部分：

settings.AUTH_USER_MODEL,

方法二：等待官方修复

Wagtail团队已经在GitHub上提交了修复该问题的补丁（#12231）。开发者可以选择：

1. 等待下一个包含该修复的Wagtail版本发布
2. 直接从GitHub仓库安装修复后的版本

技术原理

这个问题的本质是Django应用初始化顺序的时序问题。在Django启动过程中：

1. 首先加载所有应用的模型
2. 然后初始化应用注册表
3. 最后才完全建立模型间的关系

直接使用get_user_model()会在模型加载阶段就尝试访问用户模型，而此时自定义用户模型可能尚未被注册。改为使用settings.AUTH_USER_MODEL则是惰性引用，可以避免这种时序问题。

最佳实践

为了避免类似问题，在使用自定义用户模型时建议：

1. 确保自定义用户模型应用在INSTALLED_APPS中位于django.contrib.auth之前
2. 避免在模块级别直接调用get_user_model()
3. 在需要用户模型的地方使用惰性引用方式

总结

Wagtail 6.2版本中引入的这个自定义用户模型问题主要是由于代码时序导致的。通过修改源码或等待官方修复都可以解决该问题。理解Django应用初始化顺序对于处理这类问题非常有帮助，也能帮助开发者在未来避免类似的陷阱。