Wagtail页面校验：非zip格式照片时阻止保存并返回管理端错误

嘿，我来帮你搞定这个需求！要实现“非ZIP格式的文件不允许保存页面，并在后台显示错误提示”，核心是利用Wagtail页面模型的clean()方法做自定义验证——这是Django/Wagtail生态里做模型级校验的标准方式，能确保在页面保存前就拦截不符合要求的文件。

下面分两种常见场景给你具体实现代码：

场景1：直接使用FileField存储文件 #

如果你的页面模型里用的是原生Django的FileField来上传文件，代码可以这么写：

from wagtail.models import Page
from wagtail.admin.panels import FieldPanel
from django.db import models
from django.core.exceptions import ValidationError
import os

class PhotoArchivePage(Page):
    # 定义文件字段，这里设为必填，你可以根据需求调整blank/null参数
    photo_archive = models.FileField(
        upload_to='photo_archives',
        blank=False,
        null=False,
        verbose_name="照片压缩包"
    )

    # 后台管理面板配置
    content_panels = Page.content_panels + [
        FieldPanel('photo_archive'),
    ]

    def clean(self):
        # 先调用父类的clean方法，执行Wagtail默认的页面验证逻辑
        super().clean()
        
        # 检查文件是否存在，然后验证扩展名
        if self.photo_archive:
            # 拆分文件名和扩展名，转小写避免大小写问题（比如.ZIP/.Zip）
            file_ext = os.path.splitext(self.photo_archive.name)[1].lower()
            if file_ext != '.zip':
                # 抛出关联到对应字段的验证错误，错误提示会显示在该字段下方
                raise ValidationError({
                    'photo_archive': "请上传ZIP格式的压缩包！当前文件格式不符合要求。"
                })

场景2：使用Wagtail的DocumentChooserPanel关联文档 #

如果你的项目用Wagtail的Document模型来管理文件（通过DocumentChooserPanel选择已有文档），代码需要稍作调整：

from wagtail.models import Page, Document
from wagtail.admin.panels import DocumentChooserPanel
from django.db import models
from django.core.exceptions import ValidationError
import os

class PhotoArchivePage(Page):
    # 关联Wagtail的Document模型
    photo_archive = models.ForeignKey(
        Document,
        on_delete=models.SET_NULL,
        blank=False,
        null=False,
        related_name='+',
        verbose_name="照片压缩包"
    )

    content_panels = Page.content_panels + [
        DocumentChooserPanel('photo_archive'),
    ]

    def clean(self):
        super().clean()
        
        if self.photo_archive:
            # 这里要取Document关联的file字段来获取扩展名
            file_ext = os.path.splitext(self.photo_archive.file.name)[1].lower()
            if file_ext != '.zip':
                raise ValidationError({
                    'photo_archive': "请选择ZIP格式的文档！当前选中的文件不是ZIP格式。"
                })

关键注意事项 #

• 必须调用super().clean()：这一步会执行Wagtail页面模型默认的验证逻辑（比如页面标题必填、URL唯一性等），不要漏掉，否则可能导致其他验证失效。
• 错误提示关联字段：抛出ValidationError时要指定字段名（比如'photo_archive'），这样错误信息会精准显示在对应字段的下方，而不是页面顶部的通用提示区，用户体验更好。
• 处理可选字段：如果你的文件字段是可选的（blank=True），一定要保留if self.photo_archive的判断，避免用户没上传文件时触发错误。

为什么之前的尝试可能没生效？ #

如果之前的验证没起作用，大概率是这几个原因：

1. 没有正确重写clean()方法：比如拼写错误，或者没有调用父类的clean()。
2. 错误没有关联到指定字段：如果直接抛出不带字段的ValidationError，Wagtail可能不会正确显示在后台对应位置，看起来像是没生效。
3. 用了前端验证但没做后端验证：前端验证容易被绕过，必须在模型层做后端校验才可靠。

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