Skip to main content

文件上传

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

警告

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

基本文件上传

考虑一个包含 FileField 的简单表单:

forms.py
from django import forms

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

处理此表单的视图将接收 request.FILES 中的文件数据,request.FILES 是包含表单中每个 FileField (或 ImageField 或其他 FileField 子类)的键的字典。因此,来自上述形式的数据可以作为 request.FILES['file'] 访问。

注意,如果请求方法是 POST,并且发布请求的 <form> 具有属性 enctype="multipart/form-data",则 request.FILES 将仅包含数据。否则,request.FILES 将为空。

大多数时候,你只需将文件数据从 request 传递到 将上传的文件绑定到表单 中描述的表单。这看起来像:

views.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() 时,文件对象将被保存到由相应 FileFieldupload_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属性:

forms.py
from django import forms

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

然后覆盖您的 FormView 子类的 post 方法以处理多个文件上传:

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

class FileFieldView(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将文件数据传递给 上传处理程序 - 一个处理文件数据上传的小类。上传处理程序最初在 FILE_UPLOAD_HANDLERS 设置中定义,默认为:

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

MemoryFileUploadHandlerTemporaryFileUploadHandler 共同提供了Django的默认文件上传行为,即将小文件读入内存,将大文件读入磁盘。

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

存储上传的数据的位置

在保存上传的文件之前,数据需要存储在某处。

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

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

这些细节 - 2.5兆字节; /tmp;等等 - 只是“合理的默认值”,可以按照下一节中所述进行定制。

更改上传处理程序行为

有几个设置可以控制Django的文件上传行为。有关详细信息,请参阅 文件上传设置

立即修改上传处理程序

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

例如,假设您编写了一个 ProgressBarUploadHandler,它提供有关上传进度的反馈给某种AJAX小部件。您可以像这样将此处理程序添加到您的上传处理程序:

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

你可能想在这种情况下使用 list.insert() (而不是 append()),因为进度条处理程序需要运行 before 任何其他处理程序。记住,上传处理程序是按顺序处理的。

如果要完全替换上传处理程序,您只需分配一个新列表:

request.upload_handlers = [ProgressBarUploadHandler(request)]

注解

您只能修改上传处理程序访问 request.POSTrequest.FILESbefore - 在上传处理已经开始后更改上传处理程序没有意义。如果你尝试在从 request.POSTrequest.FILES 读取之后修改 request.upload_handlers,Django会抛出一个错误。

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

此外,request.POSTCsrfViewMiddleware 访问,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