Django扩展User模型时ImageField未在Admin表单显示问题

问题表现 #

扩展Django内置User模型新增个人资料图片上传能力时，Admin后台未出现图片上传/保存选项，其余扩展字段可正常展示。

相关代码 #

models.py

class Profile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    first_name = models.TextField(default='', blank='')
    last_name = models.TextField(default='', blank='')

    def save(self, *args, **kwargs):
        super().save(*args, **kwargs)


def user_image_upload_handler(instance, filename):
    fpath = pathlib.Path(filename)
    new_fname = str(uuid.uuid1())  # uuid1生成带时间戳的唯一文件名
    return f"request/{new_fname}{fpath.suffix}"


class ProfilePicture(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    image = models.ImageField(upload_to=user_image_upload_handler, blank=True)

admin.py

from django.contrib import admin
from django.contrib.auth.models import User
from .models import Profile, ProfilePicture


class ProfileAdmin(admin.ModelAdmin):
    model = [Profile]
    list_display = ['id']


class ProfilePictureAdmin(admin.ModelAdmin):
    model = [ProfilePicture]
    extra = 10


class UserAdmin(admin.ModelAdmin):
    model = ProfileAdmin
    model = ProfilePictureAdmin


admin.site.unregister(User)
admin.site.register(User, UserAdmin)

后台页面截图

问题根因 #

• ModelAdmin的model属性仅支持接收单个模型类，传入列表、其他ModelAdmin类都属于无效写法，原有配置里model = [Profile]、重复给UserAdmin的model属性赋值的写法完全不生效，根本没有把关联模型的字段挂载到User的Admin页面上。
• 要在User的编辑页展示一对一关联的模型字段，必须使用Django Admin的Inline（内联）机制，不能直接通过给model属性赋值实现。
• 额外注意：ImageField依赖Pillow库，且需要正确配置媒体文件路由、存储路径，否则就算字段正常显示也无法完成上传、预览。

修复步骤 #

1. 重写admin.py配置，使用内联方式挂载关联模型：

from django.contrib import admin
from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from django.contrib.auth.models import User
from .models import Profile, ProfilePicture


# Profile模型内联配置
class ProfileInline(admin.StackedInline):
    model = Profile
    can_delete = False

# 头像模型内联配置
class ProfilePictureInline(admin.StackedInline):
    model = ProfilePicture
    can_delete = False
    extra = 1

# 继承Django默认UserAdmin，注入内联配置
class UserAdmin(BaseUserAdmin):
    inlines = [ProfileInline, ProfilePictureInline]

# 重新注册User模型
admin.site.unregister(User)
admin.site.register(User, UserAdmin)

2. 检查依赖与基础配置

• 安装Pillow依赖：执行命令pip install pillow
• 在项目settings.py中添加媒体文件配置：

import os
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

• 开发环境下在项目根urls.py中添加媒体文件访问路由：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # 原有业务路由
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

配置完成后重启Django服务，进入User编辑页面即可看到图片上传控件。

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