Django中CheckboxSelectMultiple()选项重复（复选框+单选框）的原因与解决

问题现象 #

创建表单MyForm并为value字段指定CheckboxSelectMultiple widget，期望实现多选复选框，但渲染后出现两组重复选项：一组是方形复选框，另一组是圆形单选框。

问题原因 #

1. 表单未正确继承ModelForm：原代码中MyForm没有继承forms.ModelForm，导致Django无法正确关联模型字段的配置，会自动生成默认的字段渲染逻辑，和手动指定的widget形成重复。
2. 模型字段类型与widget不匹配：如果模型中value字段是ForeignKey（默认对应单选框），手动强制设置复选框widget后，Django可能同时渲染默认的单选控件和自定义的复选控件，造成重复。
3. django-crispy-forms的冲突渲染：若使用该库，当表单的widget配置与crispy的自动字段渲染逻辑冲突时，会重复输出字段——比如crispy根据模型字段类型生成一组控件，手动配置的widget又生成另一组。

解决步骤 #

• 修正表单继承关系：确保表单继承自forms.ModelForm，这是模型表单的基础要求：

from django import forms
from .models import X

class MyForm(forms.ModelForm):
    class Meta:
        model = X
        fields = ['value']
        widgets = {'value': forms.CheckboxSelectMultiple()}

• 匹配模型字段类型：如果需要多选功能，模型中的value字段应改为ManyToManyField，而非ForeignKey，这样字段本身就支持多选，避免类型不匹配导致的重复渲染。
• 排查crispy-forms配置：使用该库时，检查表单布局配置，确保没有重复添加value字段——比如不要同时使用Layout('__all__')和单独指定该字段，也不要在表单__init__方法中重复设置widget。

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