Django-上传文件
这篇讲什么
- 上传表单必须同时满足
method="post"和enctype="multipart/form-data",缺一个 Django 就收不到文件。 - 这篇从表单写到
UploadedFile对象、模型字段的upload_to、两种保存写法、文件存哪里又怎么访问,两个大小阈值的默认值也是实测出来的。基线 Django 5.2.19。
表单侧的两个必须项
-
上传表单必须同时满足:
method="post"且enctype="multipart/form-data"。1
2
3
4
5<form method="post" enctype="multipart/form-data" action="/upload/">
{% csrf_token %}
<input type="file" name="docs" multiple>
<input type="submit" value="上传">
</form> -
少了
enctype会怎样?实测(用urlencoded方式提交同一个字段):1
没写 enctype(urlencoded 提交): 200 {'FILES 键': [], 'POST 里那个字段': "'c.txt'"}
也就是文件内容根本没上传,
request.POST里只收到一个文件名字符串,request.FILES是空的。这是新手最常见的「上传没反应」。 -
多文件用
multiple+getlist:1
files = request.FILES.getlist("docs") # 单个文件时用 request.FILES["docs"]
实测两个文件一起提交:
1
2
3多文件: 200 {'count': 2, 'saved': [
{'name': 'a.txt', 'size': 5, 'type': 'text/plain', 'path': 'docs/20261104/a_VtqfKUE.txt', 'chunks': False},
{'name': 'b.txt', 'size': 6, 'type': 'text/plain', 'path': 'docs/20261104/b.txt', 'chunks': False}]}
UploadedFile 对象
-
request.FILES里每个值都是UploadedFile(内存里是InMemoryUploadedFile,太大时是TemporaryFileUploadedFile),常用属性方法:名称 含义 实测 .name客户端传来的文件名 a.txt.size字节数 5.content_typeMIME text/plain.multiple_chunks()是否需要分块读 False(小文件).chunks()迭代分块内容 大文件才用 .read()/.temporary_file_path()直接读 / 拿临时文件路径 后者只对落盘的临时文件有效 -
别把整个文件
read()进内存处理大图,用chunks()或者交给ImageField校验。
模型字段与 upload_to
1 | from django.db import models |
-
upload_to三种写法:- 字符串目录
"docs/"; - 带
%Y/%m/%d的 strftime 模板"docs/%Y%m%d/"(实测落盘docs/20261104/b.txt); - 可调用对象
callable(instance, filename),返回相对路径(实测pics/abc/r_lGDMsni.png)。
- 字符串目录
-
写成 lambda 会直接卡住迁移,实测原文:
1
ValueError: Cannot serialize function: lambda
因为迁移文件要把这个 callable 写进代码,匿名函数没法序列化。改成模块级具名函数即可。
-
同名文件不会被覆盖,Django 会加随机后缀:实测第二次上传
a.txt变成a_VtqfKUE.txt。 -
ImageField需要 Pillow(本机Pillow 13.0.0)。传一个非图片文件,实测表单校验:1
2非图片: False {'pic': ['Upload a valid image. The file you uploaded was either not an image or a corrupted image.']}
真图片: True {}注意它不看扩展名,看内容:把
.txt改名成.png也过不了。
保存文件的两种写法
-
手动(老笔记那种)
views.py 1
2
3
4
5def upload(request):
f = request.FILES["doc"]
art = Article(title=f.name, file=f) # 把 UploadedFile 直接赋给 FileField
art.save() # 落盘 + 写库
return JsonResponse({"path": art.file.name}) -
用
ModelForm(推荐)forms.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15class PictureForm(forms.ModelForm):
class Meta:
model = Picture
fields = ["title", "pic"]
def new_picture(request):
if request.method == "POST":
form = PictureForm(request.POST, request.FILES) # 文件要传第二个参数
if form.is_valid():
obj = form.save()
return HttpResponse(obj.pic.name)
else:
form = PictureForm()
return render(request, "myapp/picture.html", {"form": form})request.POST和request.FILES都要给,漏了FILES就报「此字段是必需的」。
存哪里、怎么访问
1 | MEDIA_ROOT = BASE_DIR / "media" |
1 | from django.conf import settings |
-
static()这个辅助函数只在DEBUG=True时有效,用来开发期直接访问上传的文件。生产环境要交给 Nginx:location /media { alias /path/to/media; }。 -
模板里取地址用
{{ article.file.url }},取磁盘路径用article.file.path。 -
实测上传后磁盘上的文件:
1
2
3
4落盘: media/docs/20261104/a.txt
落盘: media/docs/20261104/a_VtqfKUE.txt
落盘: media/docs/20261104/b.txt
落盘: media/pics/abc/r.png -
换存储后端(OSS/S3)时改
DEFAULT_FILE_STORAGE(5.2 里更推荐STORAGES["default"]["BACKEND"]),业务代码不用动 —— 别在视图里手写磁盘路径。
两个大小阈值(实测默认值)
1 | FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440 # 2.5 MB:单个上传文件超过它就先写临时文件 |
-
超过
DATA_UPLOAD_MAX_MEMORY_SIZE时,读request.body会抛异常,实测:1
超大请求体: 400 RequestDataTooBig: Request body exceeded settings.DATA_UPLOAD_MAX_MEMORY_SIZE.
常见触发场景:用
request.body接收大 JSON、或者把文件塞进 base64 放表单里。要放宽就调这个设置,别改成None。 -
FILE_UPLOAD_MAX_MEMORY_SIZE不是「禁止上传大小」,只决定「先进内存还是先落临时文件」。Django 本身没有「文件大小上限」这一项,要限制体积得自己在表单/序列化器里校验f.size。
新手卡点清单
-
都是实测过的:
卡点 症状 正确做法 表单忘写 enctyperequest.FILES为空,POST 里只有文件名字符串enctype="multipart/form-data"多文件用 request.FILES["docs"]只拿到最后一个 用 getlist("docs")upload_to写 lambdaValueError: Cannot serialize function: lambda模块级具名函数 以为同名会覆盖 实际存成 a_VtqfKUE.txt需要固定名就自己处理 File对象只改扩展名伪装图片 Upload a valid image...内容校验,别只信后缀 ModelForm没传request.FILES报「此字段是必需的」 PictureForm(request.POST, request.FILES)生产环境还指望 static()服务/media/404 交给 Nginx,或用对象存储后端 想限制上传大小却没设任何校验 大文件照样进来 自己校验 f.size;DATA_UPLOAD_MAX_MEMORY_SIZE只管非文件部分
参考
- Django:Handling uploaded files:
UploadedFile、两个大小阈值、上传流程。 FileField/ImageField参考:upload_to的三种形式与 callable 要求。django.conf.urls.static.static:开发期服务MEDIA的实现(只在 DEBUG 生效)。- Pillow:
ImageField的内容校验依赖它。