Django/Wagtail全新安装后媒体文件未在管理后台显示

我在开发环境维护一个包含media文件夹的站点，全新搭建（空数据库）、执行完所有迁移并启动站点后，发现media文件夹里已有的图片和资源没在管理后台显示，但文件实际存在。只有重新导入图片，才能在后台正常显示。想请教：为什么全新搭建时管理后台不会自动导入media文件夹中的现有文件？

使用版本：

django==3.2
wagtail==3.0

base.py配置：

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

urls.py配置：

from django.conf import settings
from django.conf.urls import include, url
from django.contrib import admin

from wagtail.admin import urls as wagtailadmin_urls
from wagtail.core import urls as wagtail_urls
from wagtail.documents import urls as wagtaildocs_urls
from wagtail.contrib.sitemaps.views import sitemap

from search import views as search_views


urlpatterns = [
    ...
]

if settings.DEBUG:
    from django.conf.urls.static import static
    from django.contrib.staticfiles.urls import staticfiles_urlpatterns


    # Serve static and media files from development server
    urlpatterns += staticfiles_urlpatterns()
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

核心原因 #

Wagtail（以及底层的Django）的媒体文件管理采用数据库记录与物理文件分离的设计：

• 后台媒体库显示的内容，本质是数据库中Image、Document等模型的实例，这些记录存储了文件的路径、名称、元数据（比如图片标题、尺寸）等信息。
• MEDIA_ROOT文件夹只是物理文件的存储位置，Wagtail不会主动扫描这个文件夹来自动创建对应的数据库记录。空数据库状态下没有这些模型实例，所以后台看不到任何文件。
• 手动导入图片时，Wagtail会为每个文件创建对应的模型记录并写入数据库，后台才能读取到这些条目并展示。

这种设计是为了支持更复杂的媒体管理需求：比如添加元数据、权限控制、版本追踪、关联到页面内容等，而非单纯做一个文件浏览器。

批量导入现有媒体文件的方法 #

如果有大量现有媒体文件需要导入，可以写一个简单的自定义脚本批量创建数据库记录：

示例：批量导入图片 #

创建import_media.py文件放在项目根目录，内容如下：

import os
from django.conf import settings
from wagtail.images.models import Image

# 定义需要导入的图片格式
ALLOWED_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.gif', '.webp']

def import_existing_images():
    media_root = settings.MEDIA_ROOT
    for root, _, files in os.walk(media_root):
        for file_name in files:
            file_ext = os.path.splitext(file_name)[1].lower()
            if file_ext not in ALLOWED_EXTENSIONS:
                continue
            
            # 构建文件的相对路径（对应Image模型的file字段）
            full_path = os.path.join(root, file_name)
            relative_path = os.path.relpath(full_path, media_root)
            
            # 避免重复导入
            if not Image.objects.filter(file=relative_path).exists():
                Image.objects.create(
                    title=os.path.splitext(file_name)[0],  # 用文件名作为标题
                    file=relative_path
                )
                print(f"已导入: {file_name}")

if __name__ == "__main__":
    import django
    django.setup()
    import_existing_images()

运行脚本：

python manage.py shell < import_media.py

扩展：导入文档 #

如果需要导入文档，只需把脚本中的wagtail.images.models.Image替换为wagtail.documents.models.Document，并调整允许的文件格式即可。

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