HTMX表单搭配Django无法成功上传文件的问题排查

我编写了如下Django表单、HTMX代码和视图函数，当用户上传文件并提交表单时，文件信息出现在response.POST中，但response.FILES为空，请问这可能是什么原因？

Django表单代码 #

class FormCotacao(forms.Form):
    descricao = forms.CharField(
        label = 'Descrição',
        max_length = 200,
        required = True
    )
    valor1 = forms.FloatField(
        label = "Valor 1 (R$)",
        required = True
    )
    orcamento1 = forms.FileField(
        label = "Orçamento 1",
        widget = forms.FileInput(attrs={'accept': '.pdf, .xls, .xlsx'}),
        required = True
    )

HTMX表单代码 #

{% load crispy_forms_tags %}
<form method="post" enctype="multipart/form-data" hx-enconding="multipart/form-data" action="">
    {% csrf_token %}
    {{ form|crispy }}
    <input type="hidden" name="id" value="{{ orcamento.id }}">
    <input type="hidden" name="acao" value="addItemCotacao">
    <button type="button" class="btn btn-secondary" hx-get="{% url 'visualizar-orcamento' id %}" hx-swap="innerHTML" hx-target="#itemsAdicionados">Cancelar</button>
    <button type="submit" hx-post="{% url 'item-cotacao' id %}" hx-swap="innerHTML" hx-target="#itemsAdicionados" class="btn btn-primary" name="addItemCotacao">Salvar item</button>
</form>

视图函数代码 #

def orcamentoCotacao(response, id):

    usuario = response.user
    orcamento = Orcamento.objects.get(id=id)

    if orcamento.aprovado != True:

        if response.method == 'POST':
            form = FormCotacao(response.POST)
            arquivos = response.FILES
            if form.is_valid():
                pass
        else:
            form = FormCotacao()
            context = {
                'form': form,
                'id': id
            }
            return render(response, "main/partials/item-cotacao.html", context)

原因与修正方案 #

1. HTMX属性拼写错误 #

你在表单里写的hx-enconding是拼写错误，正确属性名是hx-encoding（少了一个字母i）。这个属性用于告诉HTMX处理多部分表单数据，拼写错误会导致HTMX无法正确识别文件上传逻辑，最终文件数据无法进入response.FILES。

修正：
将表单中的hx-enconding="multipart/form-data"改为hx-encoding="multipart/form-data"。

2. 表单初始化未传入FILES #

视图的POST分支中，初始化FormCotacao时只传入了response.POST，没有传入response.FILES。Django表单要处理文件字段，必须同时接收POST数据和FILES数据，否则文件字段无法被解析，response.FILES会为空。

修正：
将form = FormCotacao(response.POST)改为：

form = FormCotacao(response.POST, response.FILES)

3. 额外检查点 #

确保form标签的enctype="multipart/form-data"属性没有被其他代码覆盖，配合正确的hx-encoding属性，才能保证文件上传流程正常。

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