Django自定义UserAdmin报错：Unknown field(s) (username) specified for User

核心原因 #

自定义User模型移除了username字段，但Django默认的UserAdmin类仍在引用这个字段，导致后台添加/修改用户时触发错误。

解决步骤 #

1. 完全重写CustomUserAdmin的配置 #

自定义CustomUserAdmin时，必须显式覆盖所有涉及username的属性，彻底清除对该字段的引用：

from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import CustomUser

class CustomUserAdmin(UserAdmin):
    # 后台列表显示字段
    list_display = ('email', 'first_name', 'last_name', 'is_staff', 'is_active')
    # 编辑页面的字段分组
    fieldsets = (
        (None, {'fields': ('email', 'password')}),
        ('个人信息', {'fields': ('first_name', 'last_name')}),
        ('权限设置', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
        ('重要日期', {'fields': ('last_login', 'date_joined')}),
    )
    # 添加用户页面的字段
    add_fieldsets = (
        (None, {
            'classes': ('wide',),
            'fields': ('email', 'password1', 'password2', 'is_staff', 'is_active')}
        ),
    )
    # 搜索字段改为email
    search_fields = ('email',)
    # 默认排序字段
    ordering = ('email',)
    # 和模型保持一致的USERNAME_FIELD
    USERNAME_FIELD = 'email'
    # 无需额外必填字段（email已作为登录标识）
    REQUIRED_FIELDS = []

2. 自定义用户表单（关键） #

默认的UserCreationForm依赖username字段，必须自定义表单适配你的CustomUser模型：

from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from .models import CustomUser

class CustomUserCreationForm(UserCreationForm):
    class Meta:
        model = CustomUser
        fields = ('email',)

class CustomUserChangeForm(UserChangeForm):
    class Meta:
        model = CustomUser
        fields = ('email', 'password', 'first_name', 'last_name', 'is_staff', 'is_active')

然后在CustomUserAdmin中绑定这两个表单：

class CustomUserAdmin(UserAdmin):
    # ... 其他配置 ...
    form = CustomUserChangeForm
    add_form = CustomUserCreationForm

3. 正确注册自定义用户模型 #

确保admin.py中注册的是你的CustomUser和对应的CustomUserAdmin，而非默认的User：

admin.site.register(CustomUser, CustomUserAdmin)

4. 验证settings.py配置 #

确认settings.py已指定自定义用户模型：

AUTH_USER_MODEL = '你的应用名.CustomUser'

5. 清理缓存并重启服务 #

如果之前有错误的迁移或缓存残留，执行以下操作：

• 删除migrations目录下除__init__.py外的所有文件
• 重新生成迁移：python manage.py makemigrations
• 应用迁移：python manage.py migrate
• 重启Django开发服务器

常见排查点 #

• 检查是否有第三方应用或其他代码仍在引用默认的User模型，导致冲突
• 确认CustomUser模型中确实没有username字段，且email字段已设置unique=True，USERNAME_FIELD = 'email'配置正确

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