文件上传¶
当 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 中接收文件数据，这是一个字典，其中包含表单中每个 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。
使用模型处理上传的文件¶
如果您正在 Model 上使用 FileField 保存文件，则使用 ModelForm 会使此过程变得容易得多。调用 form.save() 时，文件对象将保存到由相应 FileField 的 upload_to 参数指定的 location。
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})
如果您在请求之外手动构造对象，则可以将类似于 File 的对象分配给 FileField
from django.core.management.base import BaseCommand
from django.core.files.base import ContentFile
class MyCommand(BaseCommand):
def handle(self, *args, **options):
content_file = ContentFile(b"Hello world!", name="hello-world.txt")
instance = ModelWithFileField(file_field=content_file)
instance.save()
上传多个文件¶
如果您想使用一个表单字段上传多个文件，请创建该字段的 widget 的子类，并将其 allow_multiple_selected 类属性设置为 True。
为了让这些文件都通过您的表单验证（并使字段的值包含所有这些文件），您还必须创建 FileField 的子类。请参见下面的示例。
多文件字段
Django 未来某个时间点可能会提供合适的多个文件字段支持。
forms.py¶from django import forms
class MultipleFileInput(forms.ClearableFileInput):
allow_multiple_selected = True
class MultipleFileField(forms.FileField):
def __init__(self, *args, **kwargs):
kwargs.setdefault("widget", MultipleFileInput())
super().__init__(*args, **kwargs)
def clean(self, data, initial=None):
single_file_clean = super().clean
if isinstance(data, (list, tuple)):
result = [single_file_clean(d, initial) for d in data]
else:
result = [single_file_clean(data, initial)]
return result
class FileFieldForm(forms.Form):
file_field = MultipleFileField()
然后重写 FormView 子类的 form_valid() 方法以处理多个文件上传
views.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 form_valid(self, form):
files = form.cleaned_data["file_field"]
for f in files:
... # Do something with each file.
return super().form_valid(form)
警告
这将允许您仅在表单级别处理多个文件。请注意，您不能使用它将多个文件放在单个模型实例（在一个字段中），例如，即使自定义 widget 与与模型 FileField 相关的表单字段一起使用。
上传处理程序¶
当用户上传文件时，Django 会将文件数据传递给一个 *上传处理程序* – 一个处理上传文件数据的小型类。上传处理程序最初在 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 的文件上传行为。有关详细信息，请参阅 文件上传设置。
动态修改上传处理程序¶
有时特定视图需要不同的上传行为。在这种情况下，您可以通过修改request.upload_handlers来按每个请求覆盖上传处理器。默认情况下，此列表将包含由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
...
如果您使用的是基于类的视图，则需要在其dispatch()方法上使用csrf_exempt()，并在实际处理请求的方法上使用csrf_protect()。示例代码
from django.utils.decorators import method_decorator
from django.views import View
from django.views.decorators.csrf import csrf_exempt, csrf_protect
@method_decorator(csrf_exempt, name="dispatch")
class UploadFileView(View):
def setup(self, request, *args, **kwargs):
request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
super().setup(request, *args, **kwargs)
@method_decorator(csrf_protect)
def post(self, request, *args, **kwargs):
# Process request
...
