Wagtail-Footnotes实现故障：脚注在前后端显示为[UUID]

问题概述 #

按官方文档配置Wagtail-Footnotes后，脚注在管理后台和前端均显示为[UUID]，同时存在以下异常：

• 模板中引入的wagtail_footnotes/includes/footnotes.html内的{% for footnote in page.footnotes_list %}循环未执行
• 尝试将body字段改为RichTextBlockWithFootnotes类型时触发django.core.exceptions.FieldError: Unknown field(s) (body) specified for BlogPage

核心问题分析 #

1. 字段类型不匹配：RichTextBlockWithFootnotes是StreamField专用的块类型，不能直接作为模型字段使用，直接替换会触发字段错误
2. 未继承必要Mixin：未继承FootnotesMixin导致page.footnotes_list属性不存在，模板循环无法执行
3. 渲染方式错误：使用默认的richtext过滤器渲染普通RichTextField，无法将脚注UUID替换为正确的标记和链接

分步解决方案 #

方案1：保留普通RichTextField，用脚注过滤器渲染 #

适合不需要将body改为StreamField的场景：

1. 更新模型继承关系
   在BlogPage模型中添加FootnotesMixin继承：

   from wagtail_footnotes.models import FootnotesMixin
   
   class BlogPage(FootnotesMixin, Page):
       body = RichTextField(blank=True, features=["bold", "italic", "ol", "ul", "hr", "link", "document-link", "footnotes"])
       # 原有extras字段、content_panels配置不变
   

2. 修改模板渲染方式
   将原有的{{ page.body|richtext }}替换为Wagtail-Footnotes提供的footnotes过滤器：

   {{ page.body|footnotes }}
   

方案2：改用StreamField+RichTextBlockWithFootnotes（推荐） #

这是官方推荐的用法，能同时解决后台和前端的显示问题：

1. 重构body字段为StreamField
   将原有的RichTextField替换为包含RichTextBlockWithFootnotes的StreamField：

   from wagtail.fields import StreamField
   from wagtail_footnotes.blocks import RichTextBlockWithFootnotes
   from wagtail_footnotes.models import FootnotesMixin
   
   class BlogPage(FootnotesMixin, Page):
       # 替换原有body字段
       body = StreamField([
           ('rich_text', RichTextBlockWithFootnotes(
               label="富文本（带脚注）",
               features=["bold", "italic", "ol", "ul", "hr", "link", "footnotes", "document-link"]
           )),
       ], null=True, blank=True, use_json_field=True)
   
       extras = StreamField([
           ("testimonial", SnippetChooserBlock(
               target_model='testimonials.Testimonial',
               template="streams/testimonial_block.html"
           )),
           ("rich_text_with_footnotes", RichTextBlockWithFootnotes(
               label="富文本（带脚注）",
               features=["bold", "italic", "ol", "ul", "hr", "link", "footnotes", "document-link"]
           )),
           ("large_image", blocks.ImageChooserBlock(
               template="streams/large_image_block.html"
           )),
       ], null=True, blank=True, use_json_field=True)
   
       content_panels = Page.content_panels + [
           FieldPanel('body'),
           FieldPanel("extras"),
           InlinePanel('footnotes', label="脚注")
       ]
   

2. 模板中渲染StreamField
   按StreamField的标准方式渲染，块会自动处理脚注解析：

   {% for block in page.body %}
       {{ block }}
   {% endfor %}
   
   <!-- extras字段中的富文本块同理 -->
   {% for block in page.extras %}
       {{ block }}
   {% endfor %}
   

模板脚注列表加载修正 #

确保脚注列表在正文渲染之后引入，且模型已继承FootnotesMixin：

{% block content %}
    <!-- 先渲染所有正文内容 -->
    {% for block in page.body %}{{ block }}{% endfor %}
    {% for block in page.extras %}{{ block }}{% endfor %}

    <!-- 再加载脚注列表 -->
    {% include "wagtail_footnotes/includes/footnotes.html" %}
{% endblock %}

后台显示修复 #

改用RichTextBlockWithFootnotes作为StreamField块后，管理后台的编辑器会自动加载脚注插件，不再显示[UUID]，而是直观的脚注标记。

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