Wagtail 5.2自定义图片default_attrs配置问题及改进建议

核心结论 #

你的判断完全正确：Wagtail 5.2在自定义图片AppConfig的文档描述和源码逻辑上都存在问题，并非你遗漏了配置步骤。

问题1：替换AppConfig导致迁移失败的原因 #

Wagtail官方文档要求替换INSTALLED_APPS中的wagtail.images为自定义AppConfig的描述有误。wagtail.images包含了图片模块的核心数据库迁移文件，直接替换会让Django认为这是全新应用，无法匹配原有迁移记录，从而触发迁移失败。

正确操作就是你当前的做法：保留wagtail.images在INSTALLED_APPS中，同时添加自定义AppConfig并设置唯一label（如images_custom），避免应用标签冲突。

问题2：default_attrs未生效的根源 #

你查看源码的结论准确：Wagtail 5.2中加载default_attrs的逻辑仅读取wagtail.images原生AppConfig的配置，没有适配自定义AppConfig的场景，导致你定义的default_attrs无法被模板渲染逻辑识别，自然不会添加到<picture>标签中。这属于框架的已知bug（在后续版本中可能已修复）。

临时解决办法 #

在官方修复前，可通过以下方式实现需求：

方式1：模板全局覆盖 #

复制Wagtail默认的图片渲染模板（通常在wagtailimages/templates/wagtailimages/image.html）到你的项目模板目录，手动添加默认属性：

{% load wagtailimages_tags %}

{% image self width-800 loading="lazy" %}

如果需要适配不同尺寸的图片，可以自定义模板标签，封装图片渲染逻辑，默认注入default_attrs中的属性。

方式2：修改全局设置（hack方式） #

直接修改wagtail.images的AppConfig属性（不推荐，升级框架会失效）：

# 在项目的settings.py或apps.py中
from wagtail.images.apps import WagtailImagesAppConfig

WagtailImagesAppConfig.default_attrs = {"loading": "lazy"}

后续建议 #

可以在Wagtail官方GitHub仓库提交Issue，明确描述两个问题：

1. 文档中关于替换AppConfig的错误引导；
2. 源码未读取自定义AppConfig的default_attrs的bug。

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