Django+Bootstrap5+Crispy Forms联系表单验证消息重复问题

问题背景 #

基于Django框架，使用Bootstrap 5和Crispy Forms搭建联系表单，配置了邮箱格式验证、必填项校验规则。但表单验证出错时（例如未填写邮箱提交），页面会显示两条完全一致的错误提示，移除自定义CSS/JS后问题仍存在。

相关代码 #

forms.py

from crispy_bootstrap5.bootstrap5 import FloatingField
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Div, Submit
from django import forms
from django.core.validators import EmailValidator

class CustomSubmit(Submit):
    field_classes = "btn btn-outline-primary"

class FormularioContacto(forms.Form):
    nombre = forms.CharField(
        label='Nombre',
        max_length=50,
        required=True,
    )

    email = forms.EmailField(
        label='Email',
        required=True,
        validators=[EmailValidator()],
        error_messages={'invalid': 'Correo electrónico no válido'},
    )

    contenido = forms.CharField(
        label='Mensaje',
        widget=forms.Textarea(),
        required=False,
    )

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.form_id = 'formularioContacto'
        self.helper.form_class = 'formulario'
        self.helper.form_method = 'post'
        self.helper.attrs = {'novalidate': True}  # 禁用浏览器原生验证

        self.helper.layout = Div(
            Div(
                Div(
                    FloatingField('nombre'),
                    FloatingField('email'),
                    FloatingField('contenido'),
                    Div(
                        CustomSubmit('Enviar', 'submit', css_class='btn-lg'),
                        css_class='text-center mt-3'
                    ),
                    css_class='col-md-6 mx-auto'
                ),
                css_class='row'
            ),
            css_class='container my-4'
        )

views.py

import smtplib
from django.core.mail import EmailMessage
from django.shortcuts import render, redirect
from .forms import ContactForm

def contact(request):
    contact_form = ContactForm()

    if request.method == 'POST':
        contact_form = ContactForm(request.POST)
        if contact_form.is_valid():
            # 邮件发送逻辑
            pass

    return render(request, 'contact.html', {'form': contact_form})

contact.html

{% extends 'base.html' %}
{% load crispy_forms_tags %}
{% load static %}

{% block content %}
    <div class="container">
        <form class="form" method="post">
            {% csrf_token %}
            <!-- 手动编写的表单字段与验证消息 -->
        </form>
    </div>
{% endblock %}

原因分析 #

1. 表单类引用不匹配：表单类定义为FormularioContacto，但视图中导入并使用的是ContactForm，可能存在重复表单类定义，触发双重验证逻辑。
2. Crispy布局与手动渲染冲突：表单类中通过FormHelper定义了完整布局，但模板未使用Crispy的专属渲染标签，导致Django原生错误提示与Crispy渲染的提示重复出现。
3. 重复的邮箱验证器：forms.EmailField已内置邮箱格式验证，额外添加EmailValidator()会触发两次相同的格式校验，返回重复错误信息。

解决方法 #

1. 统一表单类引用 #

修正视图中导入的表单类，确保与定义的FormularioContacto一致：

# views.py 调整后
import smtplib
from django.core.mail import EmailMessage
from django.shortcuts import render, redirect
from .forms import FormularioContacto  # 修正导入的表单类名

def contact(request):
    contact_form = FormularioContacto()

    if request.method == 'POST':
        contact_form = FormularioContacto(request.POST)
        if contact_form.is_valid():
            # 补充邮件发送逻辑
            pass

    return render(request, 'contact.html', {'form': contact_form})

2. 使用Crispy标签统一渲染表单 #

模板中删除手动编写的表单代码，改用{% crispy form %}让Crispy按预设布局渲染，避免双重错误提示：

<!-- contact.html 调整后 -->
{% extends 'base.html' %}
{% load crispy_forms_tags %}
{% load static %}

{% block content %}
    <div class="container">
        {% crispy form %}
    </div>
{% endblock %}

3. 移除重复的邮箱验证器 #

删除EmailField中额外添加的EmailValidator()，保留内置验证即可：

# forms.py 中email字段调整后
email = forms.EmailField(
    label='Email',
    required=True,
    # 移除validators=[EmailValidator()]
    error_messages={'invalid': 'Correo electrónico no válido'},
)

4. 保留novalidate配置 #

表单类中设置的{'novalidate': True}会禁用浏览器原生验证，避免与后端验证提示重复，无需修改。

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