Wagtail后台上传图片无法加载：URL加载失败问题排查

问题描述 #

在Wagtail管理后台上传的图片无法在页面显示，图片标题可正常加载，但图片URL加载失败。已检查图片存储路径及模板语法，相关信息如下：

问题截图 #

相关代码 #

home/models.py

from django.db import models
from wagtail.models import Page
from wagtail.fields import RichTextField
from wagtail.admin.panels import FieldPanel


class HomePage(Page):
    header_image = models.ForeignKey(
        'wagtailimages.Image',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+'
    )
    body = RichTextField(blank=True)
    body_detail = RichTextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel('header_image'),
        FieldPanel('body'),
        FieldPanel('body_detail'),
    ]

home_page.html

{% extends "base.html" %}
{% load static %}
{% load wagtailcore_tags %}

{% block body_class %}template-homepage{% endblock %}


{% block content %}

<link rel="stylesheet" type="text/css" href="{% static 'css/welcome_page.css' %}">

<div class="container">
    {% if page.header_image %}
    <img src="{{ page.header_image.url }}" alt="{{ page.header_image.title }}">
    {% endif %}
    <h1>{{ page.title }}</h1>
    {{ page.body|richtext }}

    <div class="homebtn_intro">
        <a href="{% slugurl 'about' %}"> <img src="{{ page.image.url }}" alt="hello"> </a>
        <a href="{% slugurl 'about' %}"> <img src="" alt="registration"> </a>
        <a href="{% slugurl 'about' %}"> <img src="" alt="donation"> </a>
    </div>

</div>

{% endblock %}

解决方案 #

1. 加载Wagtail图片模板标签库 #

在home_page.html的模板标签加载部分，添加Wagtail图片专用标签库：

{% extends "base.html" %}
{% load static %}
{% load wagtailcore_tags %}
{% load wagtailimages_tags %} {# 新增该行 #}

2. 正确渲染图片URL #

Wagtail图片不建议直接调用.url属性，推荐使用官方image标签生成图片链接，确保路径正确且支持裁剪功能。修改图片渲染代码：

{% if page.header_image %}
    {% image page.header_image original as header_img %}
    <img src="{{ header_img.url }}" alt="{{ page.header_image.title }}">
{% endif %}

或更简洁的写法（直接生成完整img标签）：

{% if page.header_image %}
    {% image page.header_image original alt=page.header_image.title %}
{% endif %}

3. 检查媒体文件配置（开发环境） #

• 在项目settings.py中确认媒体文件配置：

  from pathlib import Path
  
  BASE_DIR = Path(__file__).resolve().parent.parent
  
  MEDIA_ROOT = BASE_DIR / 'media'  # 图片本地存储路径
  MEDIA_URL = '/media/'  # 图片访问URL前缀
  

• 在项目根目录urls.py中添加媒体文件访问路由：

  from django.conf import settings
  from django.conf.urls.static import static
  from django.contrib import admin
  from django.urls import path, include
  
  urlpatterns = [
      path('admin/', admin.site.urls),
      path('', include('home.urls')),
      # 其他路由
  ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
  

  注：该配置仅适用于开发环境，生产环境需用Nginx、Apache等服务器直接处理媒体文件请求。

额外修正 #

模板中{{ page.image.url }}为错误写法，模型定义的字段是header_image，需改为{{ page.header_image.url }}（或用上述推荐的image标签写法）。

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