Django模板下载本地文件时浏览器提示File Not Found错误问题

问题核心原因 #

Django默认不会直接映射本地文件系统路径到可访问的URL，你直接在href属性中填写本地磁盘路径会触发404错误，同时浏览器出于安全策略也不允许前端页面直接访问用户本地文件系统的路径。

解决方法 #

根据你要下载的文件类型，选择对应配置方案：

场景1：下载固定静态资源文件

• 将需要下载的文件放到Django项目配置的STATICFILES_DIRS对应目录下，通常为项目根目录的static文件夹
• 调整模板代码：
  1. 模板顶部引入静态文件标签：{% load static %}
  2. 修改下载链接为：

  <a href="{% static '文件在static目录下的相对路径' %}" download target="_blank">下载</a>
  

• 开发环境下需要在项目根urls.py中添加静态文件路由配置：

  from django.conf import settings
  from django.conf.urls.static import static
  
  urlpatterns = [
      # 此处保留你原有项目的路由配置
  ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
  

• 确认settings.py中存在静态资源配置：STATIC_URL = 'static/'

场景2：下载用户上传的动态媒体文件

• 先在settings.py中配置媒体文件参数：

  MEDIA_URL = 'media/'
  # 配置为你实际存储上传文件的根目录
  MEDIA_ROOT = BASE_DIR / 'media'
  

• 开发环境下在项目根urls.py中添加媒体文件路由配置：

  urlpatterns = [
      # 此处保留你原有项目的路由配置
  ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
  

• 模板中下载链接直接调用文件对象的url属性即可，示例：

  <a href="{{ 你传入模板的文件对象.url }}" download target="_blank">下载</a>
  

可选：需要权限控制的下载实现

如果文件需要校验登录状态、用户权限才能下载，不要用上述静态/媒体文件映射方案，单独写下载视图处理：

from django.http import FileResponse, Http404
import os
from django.conf import settings

def download_file(request, filename):
    # 此处添加你的权限校验逻辑，比如校验用户是否登录、是否有对应文件的访问权限
    file_path = os.path.join(settings.MEDIA_ROOT, filename)
    if not os.path.exists(file_path):
        raise Http404("文件不存在")
    response = FileResponse(open(file_path, 'rb'))
    response['Content-Disposition'] = f'attachment; filename="{filename}"'
    return response

在urls.py中添加对应路由：

path('download/<str:filename>/', download_file, name='download_file'),

模板中下载链接修改为：

<a href="{% url 'download_file' filename='实际要下载的文件名' %}" download target="_blank">下载</a>

排查提示 #

如果配置完成后仍报错，可右键点击下载按钮复制链接，核对生成的URL路径是否和预期的文件路径匹配，检查是否存在文件名拼写错误、大小写不匹配的问题。

生产环境部署时，静态/媒体文件需要交给Nginx等反向代理服务处理，不要用Django本身提供文件服务，避免性能问题。

内容的提问来源于stack exchange，提问作者matilde