文件上传

当 Django 处理文件上传时，文件数据最终放置在 request.FILES（有关 request 对象的更多信息，请参阅请求和响应对象的文档） . 本文档解释了文件如何存储在磁盘和内存中，以及如何自定义默认行为。

警告

如果您接受来自不受信任用户的上传内容，则存在安全风险！有关缓解详细信息，请参阅有关用户上传的内容的安全指南主题。

基本文件上传

考虑一个包含 FileField 的表单：

表格.py

from django import forms

class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file = forms.FileField()

处理此表单的视图将接收 request.FILES 中的文件数据，这是一个字典，其中包含每个 FileField（或 ImageField 或其他 [ X181X]FileField 子类）的形式。因此，上述表格中的数据可以作为 request.FILES['file'] 访问。

请注意，request.FILES 仅在请求方法为 POST 时才包含数据，至少一个文件字段被实际发布，并且发布请求的 <form> 具有属性 enctype="multipart/form-data"。否则，request.FILES 将为空。

大多数情况下，您会将文件数据从 request 传递到表单中，如将上传的文件绑定到表单中所述。这看起来像：

视图.py

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm

# Imaginary function to handle an uploaded file.
from somewhere import handle_uploaded_file

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            handle_uploaded_file(request.FILES['file'])
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})

请注意，我们必须将 request.FILES 传递给表单的构造函数；这就是文件数据绑定到表单的方式。

以下是处理上传文件的常用方法：

def handle_uploaded_file(f):
    with open('some/file/name.txt', 'wb+') as destination:
        for chunk in f.chunks():
            destination.write(chunk)

循环使用 UploadedFile.chunks() 而不是使用 read() 可确保大文件不会占用系统内存。

UploadedFile 对象上还有一些其他方法和属性可用；有关完整参考，请参阅 UploadedFile。

使用模型处理上传的文件

如果您使用 FileField 在 Model 上保存文件，则使用 ModelForm 会使此过程更容易。调用 form.save() 时，文件对象将保存到对应 FileField 的 upload_to 参数指定的位置：

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import ModelFormWithFileField

def upload_file(request):
    if request.method == 'POST':
        form = ModelFormWithFileField(request.POST, request.FILES)
        if form.is_valid():
            # file is saved
            form.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = ModelFormWithFileField()
    return render(request, 'upload.html', {'form': form})

如果是手动构造对象，可以将 request.FILES 中的文件对象分配给模型中的文件字段：

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm
from .models import ModelWithFileField

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            instance = ModelWithFileField(file_field=request.FILES['file'])
            instance.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})

上传多个文件

如果要使用一个表单字段上传多个文件，请设置字段小部件的 multiple HTML 属性：

表格.py

from django import forms

class FileFieldForm(forms.Form):
    file_field = forms.FileField(widget=forms.ClearableFileInput(attrs={'multiple': True}))

然后覆盖 FormView 子类的 post 方法来处理多个文件上传：

视图.py

from django.views.generic.edit import FormView
from .forms import FileFieldForm

class FileFieldFormView(FormView):
    form_class = FileFieldForm
    template_name = 'upload.html'  # Replace with your template.
    success_url = '...'  # Replace with your URL or reverse().

    def post(self, request, *args, **kwargs):
        form_class = self.get_form_class()
        form = self.get_form(form_class)
        files = request.FILES.getlist('file_field')
        if form.is_valid():
            for f in files:
                ...  # Do something with each file.
            return self.form_valid(form)
        else:
            return self.form_invalid(form)

上传处理程序

当用户上传文件时，Django 将文件数据传递给 上传处理程序 ——一个在文件数据上传时处理文件数据的小类。上传处理程序最初在 :setting:`FILE_UPLOAD_HANDLERS` 设置中定义，默认为：

["django.core.files.uploadhandler.MemoryFileUploadHandler",
 "django.core.files.uploadhandler.TemporaryFileUploadHandler"]

MemoryFileUploadHandler 和 TemporaryFileUploadHandler 一起提供了 Django 的默认文件上传行为，将小文件读入内存，将大文件读入磁盘。

您可以编写自定义处理程序来自定义 Django 处理文件的方式。例如，您可以使用自定义处理程序来强制执行用户级配额、动态压缩数据、渲染进度条，甚至将数据直接发送到另一个存储位置，而无需将其存储在本地。有关如何自定义或完全替换上传行为的详细信息，请参阅编写自定义上传处理程序。

上传数据的存储位置

在保存上传的文件之前，数据需要存储在某个地方。

默认情况下，如果上传的文件小于 2.5 兆字节，Django 会将上传的全部内容保存在内存中。这意味着保存文件只涉及从内存读取和写入磁盘，因此速度非常快。

但是，如果上传的文件太大，Django 会将上传的文件写入存储在系统临时目录中的临时文件中。在类 Unix 平台上，这意味着您可以期望 Django 生成一个名为 /tmp/tmpzfp6I6.upload 之类的文件。如果上传足够大，您可以看到这个文件随着 Django 将数据流式传输到磁盘而变大。

这些细节 – 2.5 兆字节； /tmp; 等等。 – 是“合理的默认值”，可以按照下一节所述进行自定义。

更改上传处理程序行为

有一些设置可以控制 Django 的文件上传行为。详见【X4X】文件上传设置【X28X】。

动态修改上传处理程序

有时特定的视图需要不同的上传行为。在这些情况下，您可以通过修改 request.upload_handlers 在每个请求的基础上覆盖上传处理程序。默认情况下，此列表将包含 :setting:`FILE_UPLOAD_HANDLERS` 给出的上传处理程序，但您可以像修改任何其他列表一样修改该列表。

例如，假设您编写了一个 ProgressBarUploadHandler，它提供有关上传到某种 AJAX 小部件的进度的反馈。您可以将此处理程序添加到您的上传处理程序中，如下所示：

request.upload_handlers.insert(0, ProgressBarUploadHandler(request))

在这种情况下，您可能希望使用 list.insert()（而不是 append()），因为进度条处理程序需要在 任何其他处理程序之前运行 。请记住，上传处理程序是按顺序处理的。

如果要完全替换上传处理程序，可以分配一个新列表：

request.upload_handlers = [ProgressBarUploadHandler(request)]

笔记

您只能在 访问 request.POST 或 request.FILES 之前修改上传处理程序 - 在上传处理开始后更改上传处理程序没有意义。如果您在读取 request.POST 或 request.FILES 后尝试修改 request.upload_handlers，Django 将抛出错误。

因此，您应该始终尽可能早地在视图中修改上传处理程序。

此外，request.POST 由默认启用的 CsrfViewMiddleware 访问。这意味着您需要在视图上使用 csrf_exempt() 以允许您更改上传处理程序。然后，您需要在实际处理请求的函数上使用 csrf_protect()。请注意，这意味着处理程序可能会在 CSRF 检查完成之前开始接收文件上传。示例代码：

from django.views.decorators.csrf import csrf_exempt, csrf_protect

@csrf_exempt
def upload_file_view(request):
    request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
    return _upload_file_view(request)

@csrf_protect
def _upload_file_view(request):
    ... # Process request

文件上传 — Django 文档