你想了解在 Django 框架中实现文件上传功能的核心步骤，需要一份清晰、可落地的步骤指南，涵盖从配置到代码实现的全流程。以下是 Django 实现文件上传的 7 个核心步骤，每个步骤都包含具体配置和代码示例，适配 Django 4.x/5.x 版本。

Django 实现文件上传的核心步骤

步骤 1：配置媒体文件（Media）路径（基础前提）

Django 中上传的文件默认存储在媒体文件目录（Media），需要在settings.py中配置路径和访问 URL，这是文件上传的基础。

配置代码（settings.py）

python

# 项目根目录（拼接路径用）
import os
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# 1. 媒体文件存储路径（上传的文件会存到这个目录）
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')  # 项目根目录下的media文件夹

# 2. 媒体文件访问URL（前端/后端访问上传文件的URL前缀）
MEDIA_URL = '/media/'  # 例如：http://127.0.0.1:8000/media/xxx.jpg

# 可选：文件上传大小限制（防止超大文件上传）
DATA_UPLOAD_MAX_MEMORY_SIZE = 10485760  # 10MB（默认2.5MB）
FILE_UPLOAD_MAX_MEMORY_SIZE = 10485760   # 10MB
关键说明
  • MEDIA_ROOT：本地物理路径，必须是绝对路径，Django 会把上传的文件保存到这个目录；
  • MEDIA_URL：URL 路径，用于浏览器访问上传的文件（比如上传的图片可以通过http://域名/media/文件名访问）；
  • 需手动在项目根目录创建media文件夹（否则上传时会报路径不存在错误）。

步骤 2：配置 URL 以访问媒体文件（可选但必要）

开发环境下，需要配置 URL 路由，让 Django 能处理MEDIA_URL的访问请求（生产环境需用 Nginx 等服务器处理）。

配置代码（项目根 urls.py）

python

from django.contrib import admin
from django.urls import path
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path('admin/', admin.site.urls),
    # 其他路由...
]

# 开发环境下，添加媒体文件的访问路由
if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

步骤 3：定义包含文件字段的模型（Model）（可选，按需使用）

如果需要将文件信息（如文件名、存储路径）存入数据库，需在models.py中定义模型，核心字段是FileField（通用文件）或ImageField（图片文件，需安装Pillow）。

模型代码（app/models.py）

python

from django.db import models

class UploadFile(models.Model):
    # 1. 文件字段：upload_to指定文件存储的子目录（media下的uploads文件夹）
    file = models.FileField(upload_to='uploads/%Y/%m/%d/')  # 按年月日分目录存储
    # 可选：图片字段（需安装Pillow：pip install Pillow）
    # image = models.ImageField(upload_to='images/%Y/%m/%d/')
    
    # 2. 上传时间（自动记录）
    upload_time = models.DateTimeField(auto_now_add=True)
    
    # 可选：自定义文件名显示
    def __str__(self):
        return self.file.name
关键说明
  • upload_to：可以是字符串（固定目录）或函数（动态生成目录 / 文件名）；
  • 执行python manage.py makemigrations和python manage.py migrate创建数据库表。

步骤 4：创建文件上传表单（Form）（简化验证）

使用 Django 的表单类（Form/ModelForm）可以自动验证文件类型、大小，简化处理逻辑。

表单代码（app/forms.py）

python

from django import forms
from .models import UploadFile

# 方式1：ModelForm（关联模型，推荐）
class UploadFileForm(forms.ModelForm):
    class Meta:
        model = UploadFile
        fields = ['file']  # 对应模型中的字段
        # 可选：添加表单样式/验证
        widgets = {
            'file': forms.ClearableFileInput(attrs={'class': 'form-control'}),
        }

# 方式2：普通Form（不关联模型）
# class UploadFileForm(forms.Form):
#     file = forms.FileField(label='选择文件', widget=forms.ClearableFileInput)

步骤 5：编写视图函数 / 类（View）处理上传逻辑（核心）

视图是处理文件上传的核心，负责接收请求、验证表单、保存文件，分为函数视图和类视图两种方式。

方式 1：函数视图（简单易理解）

python

from django.shortcuts import render, redirect
from .forms import UploadFileForm

def file_upload(request):
    if request.method == 'POST':
        # 1. 绑定表单数据（包含文件）
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            # 2. 保存文件（ModelForm会自动保存到MEDIA_ROOT指定的路径）
            form.save()
            # 3. 上传成功，跳转/提示
            return render(request, 'upload_success.html', {'msg': '文件上传成功！'})
    else:
        # GET请求，显示空表单
        form = UploadFileForm()
    
    return render(request, 'upload.html', {'form': form})
方式 2：类视图（Django 推荐，更简洁）

python

from django.views.generic import FormView
from django.urls import reverse_lazy
from .forms import UploadFileForm

class FileUploadView(FormView):
    template_name = 'upload.html'  # 上传页面模板
    form_class = UploadFileForm    # 绑定的表单类
    success_url = reverse_lazy('upload_success')  # 上传成功后的跳转URL

    # 重写form_valid方法，处理文件保存
    def form_valid(self, form):
        form.save()  # 保存文件
        return super().form_valid(form)
关键说明
  • 文件上传必须用POST请求，且表单enctype需为multipart/form-data；
  • request.FILES：Django 封装的文件数据，必须传入表单才能获取上传的文件；
  • form.is_valid()：自动验证文件是否符合要求（如大小、类型）。

步骤 6：编写前端上传页面（HTML 模板）

创建模板文件，显示表单并支持文件选择和提交。

模板代码（templates/upload.html）

html

预览

<!DOCTYPE html>
<html>
<head>
    <title>文件上传</title>
</head>
<body>
    <h1>文件上传</h1>
    <!-- 必须设置enctype="multipart/form-data"才能上传文件 -->
    <form method="post" enctype="multipart/form-data">
        {% csrf_token %}  <!-- Django必加，防止CSRF攻击 -->
        {{ form.as_p }}  <!-- 渲染表单 -->
        <button type="submit">上传</button>
    </form>
</body>
</html>
成功页面（templates/upload_success.html）

html

预览

<!DOCTYPE html>
<html>
<head>
    <title>上传成功</title>
</head>
<body>
    <h1>{{ msg }}</h1>
    <a href="{% url 'file_upload' %}">返回上传页面</a>
</body>
</html>

步骤 7：配置 URL 路由（映射视图）

将视图映射到 URL，让用户可以访问上传页面。

路由代码（app/urls.py）

python

from django.urls import path
from . import views

urlpatterns = [
    # 函数视图路由
    path('upload/', views.file_upload, name='file_upload'),
    # 类视图路由（如果用类视图）
    # path('upload/', views.FileUploadView.as_view(), name='file_upload'),
    # 成功页面路由
    path('upload/success/', lambda request: render(request, 'upload_success.html'), name='upload_success'),
]

步骤 8：测试文件上传功能

  1. 启动 Django 开发服务器：python manage.py runserver；
  2. 访问http://127.0.0.1:8000/upload/；
  3. 选择文件并点击 “上传”，成功后会看到提示，且media/uploads/目录下会出现上传的文件。

进阶注意事项（生产环境必备）

  1. 文件类型验证：限制仅允许上传指定类型的文件（如.pdf、.jpg）：

    python

    # 在forms.py中添加验证
def clean_file(self):
    file = self.cleaned_data['file']
    allowed_extensions = ['pdf', 'jpg', 'png', 'txt']
    extension = file.name.split('.')[-1].lower()
    if extension not in allowed_extensions:
        raise forms.ValidationError('仅允许上传PDF、JPG、PNG、TXT文件！')
    return file
  2. 文件重命名：避免文件名重复，自定义文件名：

    python

    # 在models.py中自定义upload_to函数
def custom_upload_to(instance, filename):
    import uuid
    ext = filename.split('.')[-1]
    new_filename = f"{uuid.uuid4()}.{ext}"  # 用UUID生成唯一文件名
    return f'uploads/{new_filename}'

# 模型字段修改
file = models.FileField(upload_to=custom_upload_to)
  3. 生产环境配置：
    • 不要用 Django 处理媒体文件访问，改用 Nginx/Apache；
    • 可将文件存储到云存储（如阿里云 OSS、腾讯云 COS），需安装对应插件（如django-storages）。

总结

  1. Django 文件上传的核心是配置 Media 路径（存储 + 访问）、表单验证文件、视图处理保存三大环节；
  2. 关键要点：表单必须设置enctype="multipart/form-data"，视图需接收request.FILES，开发环境需配置 Media URL；
  3. 生产环境需增加文件类型 / 大小验证、自定义文件名、改用第三方存储 / 服务器处理文件访问。
# python # django # sqlite
Logo
魔乐社区

魔乐社区（Modelers.cn) 是一个中立、公益的人工智能社区，提供人工智能工具、模型、数据的托管、展示与应用协同服务，为人工智能开发及爱好者搭建开放的学习交流平台。社区通过理事会方式运作，由全产业链共同建设、共同运营、共同享有，推动国产AI生态繁荣发展。

更多推荐

cover

量化挑战赛冠军专访：4小时啃下W4A8量化，我靠的是这些经验

avatar 魔乐社区
cover

替你试过了，消费级显卡可以跑的开源文生图SOTA模型，顶级渲染、高密度文本绘图

avatar 魔乐社区
cover

「极限压缩 量化未来」Modelers GeekDay上海站圆满落幕

avatar 魔乐社区