Django 实现文件上传与下载：5分钟快速上手指南

Cora

发布时间：2026-10-14| 4人浏览过

原创

本文详细介绍如何在 Django 项目中实现文件上传与下载功能。通过创建 FileModel 模型、配置 settings.py、定义表单及视图函数，并在 5 分钟内完成从数据库映射到前端交互的全流程。涵盖路由配置、文件存储逻辑及下载响应处理，附带完整代码示例与测试步骤。

1. 前言

大家好，我是安果！

文件上传与下载是 Web 开发中的基础且常见功能。在 Django 框架中，如何高效地实现这一功能？

本文将通过一个简洁的示例，帮助您在 5 分钟内快速掌握 Django 文件上传与下载的核心实现方法。

2. 实战一下

以下是详细的实现步骤，共分为 9 个环节：

2-1 进入虚拟环境，创建一个项目及 App


workon django3

# 创建项目
django-admin startproject file_up_and_down_demo

# 进入项目根目录
cd file_up_and_down_demo/

# 创建一个App
django-admin startapp index

2-2 创建模板目录并配置 settings.py

在 index App 目录下新建一个 templates 文件夹，随后在项目配置文件 settings.py 中注册该 App 并指定模板目录路径。


# settings.py

# 配置App
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'index',
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            # 配置模板目录
            os.path.join(BASE_DIR, 'index/templates')
        ],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

2-3 创建文件模型，并映射到数据库

以 Django 默认的 SQLite 数据库为例，在 index App 的 models.py 文件中定义一个用于表示文件的模型类。

该模型需包含以下 3 个字段：

文件名称
文件保存路径
上传时间


# index App models.py

from django.db import models
from django.utils import timezone


# 文件模型
class FileModel(models.Model):
    # 文件名称
    name = models.CharField(max_length=50)

    # 文件保存路径
    path = models.CharField(max_length=100)

    # 上传时间
    upload_time = models.DateTimeField(default=timezone.now)

定义好模型后，在项目根目录下依次执行以下 2 条命令，将模型结构同步至数据库：


# 数据库映射
Python3 manage.py makemigrations

python3 manage.py migrate

2-4 自定义表单控件

在 index App 目录下创建 forms.py 文件。

在该文件中自定义一个表单类，使其继承自 forms.Form。


# index App forms.py

from django import forms

class FileForm(forms.Form):
    file = forms.FileField(
        # 支持多文件上传
        widget=forms.ClearableFileInput(attrs={'multiple': True}),
        label='请选择文件',
    )

2-5 添加上传、下载路由 URL

为上传和下载功能配置相应的 URL 路由。


# 项目urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('index.urls'))
]

# index App urls.py
from django.urls import path

from .views import *

urlpatterns = [
    # 上传
    path('', index_view, name='index'),

    # 下载
    path('download/<id>', download_view, name='download')
]

2-6 编写模板文件

在 index App 的 templates 文件夹中创建一个简单的模板文件 upload.html。

其中：

form 代表从视图函数传递过来的表单实体对象。
form.as_p 表示以段落格式渲染所有表单元素。


# index App upload.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>主页-上传文件</title>
</head>
<body>

<form method="post" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="确定上传">
</form>

</body>
</html>

2-7 上传视图函数

在 index App 的 views.py 中编写处理上传功能的视图函数。

请注意，需提前在项目根目录下创建一个 upload 文件夹，用于存储上传的文件。


# index App views.py

def index_view(request):
    """
    上传文件
    :param request:
    :return:
    """
    if request.method == 'POST':
        form = FileForm(request.POST, request.FILES)
        if form.is_valid():
            # 选择的文件
            files = request.FILES.getlist('file')

            # 遍历写入到数据库中
            for file in files:
                # 写入到数据库中
                file_model = FileModel(name=file.name, path=os.path.join('./upload', file.name))
                file_model.save()

                # 写入到服务器本地
                destination = open(os.path.join("./upload", file.name), 'wb+')
                for chunk in file.chunks():
                    destination.write(chunk)
                destination.close()

            # 提示上传成功
            return HttpResponse('上传成功!')
    else:
        form = FileForm()
        return render(request, 'upload.html', locals())

2-8 下载视图函数

接着，编写处理下载功能的视图函数。


# index App views.py

def download_view(request, id):
    """
    下载文件
    :param request:
    :param id:文件id
    :return:
    """
    file_result = FileModel.objects.filter(id=id)

    # 如果文件存在，就下载文件
    if file_result:

        file = list(file_result)[0]

        # 文件名称及路径
        name = file.name
        path = file.path

        # 读取文件
        file = open(path, 'rb')
        response = FileResponse(file)

        # 使用urlquote对文件名称进行编码
        response['Content-Disposition'] = 'attachment;filename="%s"' % urlquote(name)

        return response
    else:
        return HttpResponse('文件不存在!')