Django 4.1后台可上传图片但无法显示问题排查求助

问题现象 #

图片可正常上传，但Admin后台无法显示已上传的图片。

环境信息 #

• 开发服务器启动命令：python manage.py runserver --insecure 0.0.0.0:8000
• 项目根目录：C:\django\humm\humm

项目目录结构 #

- humm
    - backend
        ...
        admin.py
        models.py
        ...
    - humm
        ...
        settings.py
        urls.py
        ...
    - media
        - images
            pd.png (已成功上传的图片)

当前配置代码 #

urls.py #

from django.conf import settings
from django.conf.urls.static import static
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('', admin.site.urls),
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

models.py #

...
class Produto(models.Model):
    ...
    descricao = models.CharField(db_column='product_name', max_length=40)
    imagem_pequena = models.ImageField(db_column='small_image', upload_to='images/', blank=True, null=True)

admin.py #

...
class ProdutoAdmin(admin.ModelAdmin):

    def thumb_pequeno(self, obj):
        if obj.imagem_pequena:
            return format_html('<img src="{}" style="max-width:100px; max-height:100px"/>', obj.imagem_pequena.url)
        else:
            return '-'
    thumb_pequeno.short_description = 'pequena'

    # 曾尝试使用`imagem_pequena.allow_tags = True`，但该方法在Django 4.1中已被弃用，官方推荐使用format_html

    readonly_fields = [...,'thumb_pequeno',]
    list_display = ['descricao','thumb_pequeno',]
...
admin.site.register(Produto, ProdutoAdmin)

settings.py #

...
DEBUG = True   # 已在shell中确认值为True
...
INSTALLED_APPS = [
    ...,
    'backend'
]
...
ROOT_URLCONF = 'humm.urls'
...
BASE_DIR = Path(__file__).resolve().parent.parent
    # shell中BASE_DIR的值为：WindowsPath('C:/django/humm/humm')
 ...
STATIC_URL = 'static/'
STATIC_ROOT = BASE_DIR / 'static'
    # shell中STATIC_ROOT的值为：WindowsPath('C:/django/humm/humm/static')
...
MEDIA_URL = 'media/'
MEDIA_ROOT = BASE_DIR / 'media'
    # 也曾尝试使用`MEDIA_ROOT = os.path.join(BASE_DIR, 'media')`
    # 两种方式下，shell中MEDIA_ROOT的值均为：'C:\\django\\humm\\humm\\media'

排查与修复方案 #

1. 修正Admin中图片HTML输出（核心问题） #

当前admin.py中使用了HTML实体字符（<、"），导致输出的是文本而非有效img标签，直接修改为原始HTML标签：

def thumb_pequeno(self, obj):
    if obj.imagem_pequena:
        return format_html('<img src="{}" style="max-width:100px; max-height:100px"/>', obj.imagem_pequena.url)
    else:
        return '-'

2. 规范MEDIA_URL路径格式 #

Django 4.1要求MEDIA_URL以斜杠开头，避免路径拼接错误，修改settings.py：

MEDIA_URL = '/media/'

3. 验证静态文件映射配置 #

确保DEBUG=True时，urls.py中的静态文件映射分支生效：

• 可临时在urls.py中添加print(settings.DEBUG)，启动服务器时确认输出为True。
• 直接访问图片URL（如http://0.0.0.0:8000/media/images/pd.png），检查是否能正常打开：
  • 若返回404：确认MEDIA_ROOT指向的目录（C:\django\humm\humm\media）下存在对应图片文件。
  • 若返回403：检查Windows目录权限，确保media文件夹及子文件有可读权限。

4. 重启开发服务器 #

修改配置后必须重启runserver，确保新配置加载生效。

验证 #

完成修复后：

• 重新上传图片，查看Admin列表页和详情页的图片显示状态。
• 直接访问图片URL，确认能正常加载。

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