Django自定义用户模型报错：AUTH_USER_MODEL引用未安装模型

• 模型类名与AUTH_USER_MODEL配置不匹配
  检查api/models/userModel.py中的模型类名是否确实为UserAccount。确认类定义如下：

  class UserAccount(AbstractBaseUser, PermissionsMixin):
      # 模型字段及其他定义
  

  若类名是User或其他名称，需同步修改AUTH_USER_MODEL的配置值。

• 未在models/init.py中暴露自定义模型
  Django默认只会加载app下models.py或models/__init__.py中导入的模型。如果你的模型单独放在userModel.py文件里，必须在api/models/__init__.py中添加导入语句：

  from .userModel import UserAccount
  

  否则Django无法扫描到该模型的存在。

• app配置类的name属性错误
  打开api/apps.py，检查配置类的name属性是否严格等于'api'：

  from django.apps import AppConfig
  
  class ApiConfig(AppConfig):
      default_auto_field = 'django.db.models.BigAutoField'
      name = 'api'  # 必须与INSTALLED_APPS中注册的应用名称一致
  

  若INSTALLED_APPS中注册的是'api.apps.ApiConfig'，此处的name必须为'api'，否则Django无法将模型关联到正确的应用。

• 模型Meta类中app_label配置冲突
  如果UserAccount模型的Meta类手动指定了app_label，比如：

  class UserAccount(AbstractBaseUser, PermissionsMixin):
      class Meta:
          app_label = 'other_app'
  

  这会导致模型被归属到其他应用，与AUTH_USER_MODEL中指定的api冲突，需删除或修正该配置。

• Django配置缓存残留
  部分情况下，Django会缓存旧的配置信息，即使修改了模型或settings。可以尝试：

  • 重启终端或IDE
  • 执行py manage.py check命令，查看是否有其他隐藏的配置错误
  • 删除项目根目录及各应用下的__pycache__文件夹

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