Django文件上传与FileField配置详解

本文深入解析了Django中用户文件上传的核心机制与常见陷阱，重点阐明为何上传文件后访问返回404——根本原因在于Django默认不提供媒体文件服务，必须严格配对MEDIA_URL与MEDIA_ROOT，并在开发环境（DEBUG=True）手动挂载媒体路由，而在生产环境（DEBUG=False）则必须由Nginx或Apache直接托管/media/路径；文章还系统讲解了FileField的存储逻辑（仅存相对路径）、安全读写与手动删除要点、大文件上传配置、路径注入防护，以及极易被忽视的生产部署权限与Web服务器配置问题，帮你一次性打通从本地调试到线上稳定运行的全链路。

为什么上传的文件找不到，或者访问404？

根本原因通常是 MEDIA_ROOT 和 MEDIA_URL 没配对，或开发服务器没启用媒体文件服务。Django 默认不自动提供 MEDIA_ROOT 下的静态资源——它只管 STATIC_ROOT；上传的文件属于「媒体文件」，必须显式告诉 Django：「这些路径下的东西，允许用户通过 URL 访问」。

• MEDIA_ROOT 是绝对路径，指向服务器上存储上传文件的物理目录（比如 /var/www/myproject/media/ 或 os.path.join(BASE_DIR, 'media')）
• MEDIA_URL 是 URL 前缀（如 /media/），用户请求 https://yoursite.com/media/avatar.jpg 时，Django 才知道该去 MEDIA_ROOT 里找 avatar.jpg
• 仅配置这两个变量还不够：在开发环境（DEBUG=True），你还得在主 urls.py 中手动挂载媒体路由，否则请求直接 404

开发环境怎么让 /media/ 路径能访问上传文件？

在项目根目录的 urls.py（不是 app 里的）末尾追加这一行：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

注意：这行只能在 DEBUG=True 时生效，生产环境必须由 Nginx/Apache 直接服务 MEDIA_ROOT，绝不能靠 Django 的 static()——性能差且不安全。

• 如果加了这行还是 404，检查 settings.py 是否真设置了 MEDIA_URL = '/media/' 和 MEDIA_ROOT 为合法绝对路径
• 路径末尾斜杠要一致：MEDIA_URL 以 / 结尾，HTML 中 才能拼出正确地址
• 别把 MEDIA_ROOT 设成 STATIC_ROOT 或项目源码目录下——上传文件可能覆盖代码，或被 Git 误提交

FileField 在模型里怎么存、怎么读、怎么删？

FileField 本身不存文件内容，只存相对路径（如 uploads/avatar_abc123.png），实际文件写入 MEDIA_ROOT 对应位置。它的行为和 ImageField 几乎一样，只是少了图片校验。

• 保存时：调用 model_instance.file_field.save('name.ext', ContentFile(b'data'), save=True) 或直接表单提交（request.FILES）
• 读取时：obj.file_field.url 返回完整可访问 URL（依赖 MEDIA_URL）；obj.file_field.path 返回服务器绝对路径（依赖 MEDIA_ROOT）
• 删除时：obj.file_field.delete(save=False) —— 注意要手动调用，Django 不会自动删磁盘文件；之后再 obj.save() 更新数据库字段为空
• 别直接操作 obj.file_field.name 来改名：它只是字符串，改了不会移动文件，也不更新数据库，要用 save() 方法重写

上传大文件或特殊类型时要注意什么？

Django 默认限制 POST 数据大小（DATA_UPLOAD_MAX_MEMORY_SIZE）和单个文件大小（FILE_UPLOAD_MAX_MEMORY_SIZE），超出就抛 RequestDataTooBig 错误。

• 调大限制需在 settings.py 显式设置，例如：DATA_UPLOAD_MAX_MEMORY_SIZE = 26214400（25MB）
• 上传 ZIP/PDF 等非文本文件，确保表单 enctype="multipart/form-data"，且视图中从 request.FILES 取，不是 request.POST
• FileField(upload_to='uploads/%Y/%m/') 支持日期格式化，但注意路径是相对于 MEDIA_ROOT 的，最终存储路径类似 MEDIA_ROOT/uploads/2024/06/filename.pdf
• 用户上传路径不可信：永远不要用 request.FILES['file'].name 直接拼路径，要用 os.path.basename() 或更安全的 django.utils.text.get_valid_filename()

最常被忽略的是：生产部署时忘记配 Nginx 的 location /media/ 规则，或权限没放开，导致上传成功但前端加载不到——这时候查日志会发现 Django 根本没收到媒体请求，是 Web 服务器拦截了。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~