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_type MIME text/plain
    .multiple_chunks() 是否需要分块读 False(小文件)
    .chunks() 迭代分块内容 大文件才用
    .read() / .temporary_file_path() 直接读 / 拿临时文件路径 后者只对落盘的临时文件有效
  • 别把整个文件 read() 进内存处理大图,用 chunks() 或者交给 ImageField 校验。

模型字段与 upload_to

myapp/models.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from django.db import models


def upload_pic_path(instance, filename):
"""具名函数可以被 makemigrations 序列化;lambda 不行。"""
return "pics/%s/%s" % (instance.title, filename)


class Article(models.Model):
title = models.CharField(max_length=50)
file = models.FileField(upload_to="docs/%Y%m%d/")
image = models.ImageField(upload_to="pics/", null=True, blank=True)


class Picture(models.Model):
title = models.CharField(max_length=20, default="t")
pic = models.ImageField(upload_to=upload_pic_path)
  • upload_to 三种写法:

    1. 字符串目录 "docs/";
    2. 带 %Y/%m/%d 的 strftime 模板 "docs/%Y%m%d/"(实测落盘 docs/20261104/b.txt);
    3. 可调用对象 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
    5
    def 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
    15
    class 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 就报「此字段是必需的」。

存哪里、怎么访问

proj/settings.py
1
2
MEDIA_ROOT = BASE_DIR / "media"
MEDIA_URL = "/media/"
proj/urls.py
1
2
3
4
5
6
7
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
path("admin/", admin.site.urls),
path("", include("myapp.urls")),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
  • 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
2
3
FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440     # 2.5 MB:单个上传文件超过它就先写临时文件
DATA_UPLOAD_MAX_MEMORY_SIZE = 2621440 # 2.5 MB:整个请求体(不含文件)超过它直接拒绝
DATA_UPLOAD_MAX_NUMBER_FIELDS = 1000 # POST 字段数量上限
  • 超过 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。

新手卡点清单

  • 都是实测过的:

    卡点 症状 正确做法
    表单忘写 enctype request.FILES 为空,POST 里只有文件名字符串 enctype="multipart/form-data"
    多文件用 request.FILES["docs"] 只拿到最后一个 用 getlist("docs")
    upload_to 写 lambda ValueError: 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 只管非文件部分

参考

本文结束 感谢您的阅读
正在加载今日诗词....