Django自定义User Admin未在管理站点生效的原因排查

以下是导致自定义UserAdmin未生效的核心原因：

• 自定义UserAdmin未适配AbstractBaseUser子类
  Django自带的UserAdmin是为继承AbstractUser的默认用户模型设计的。如果你的User模型继承自AbstractBaseUser的子类，直接继承UserAdmin可能因字段不匹配（比如缺少默认User的username等字段）导致注册逻辑失效，Django会自动 fallback 到默认Admin配置。此时需要确保自定义UserAdmin重写了add_fieldsets、fieldsets等必要属性，覆盖为你的用户模型的必填字段。

• admin.py未被正确加载或存在语法错误
  若app1/admin.py存在语法错误，或文件名拼写错误（比如写成admn.py），会导致整个文件代码未执行，自定义UserAdmin根本没完成注册。Django会自动为AUTH_USER_MODEL指定的模型注册默认Admin界面，所以即使删除自定义UserAdmin，后台依然显示用户列表，只是用默认字段配置。

• 导入错误导致注册了错误的User模型
  检查app1/admin.py的User导入语句，如果误导入django.contrib.auth.models.User而非app1.models.User，那么@admin.register(User)注册的是默认用户模型，而非你的自定义User模型。此时自定义User模型会被Django自动用默认Admin注册，自然不会应用你定义的list_display和fieldsets。

• Django默认自动注册AUTH_USER_MODEL
  Django Admin框架会自动检测AUTH_USER_MODEL设置的用户模型，若该模型未被显式注册到Admin，就会自动用默认UserAdmin（或适配的Admin类）注册。这就是删除自定义UserAdmin后，后台依然能看到用户管理入口的原因——属于Django默认行为。

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