Django+Wagtail项目中下载链接预览而非直接下载的问题排查

本地用python manage.py runserver能正常触发文件下载，部署后却自动打开预览，核心是开发服务器与生产环境的媒体文件服务逻辑差异，具体原因和解决办法如下：

主要原因 #

• 跨域限制：如果部署时媒体文件使用了独立域名（如CDN、子域名），浏览器会因同源策略忽略<a>标签的download属性，直接按文件类型执行默认预览行为。
• 服务器响应头缺失：生产环境的Nginx/Apache等服务器未给媒体文件添加Content-Disposition: attachment响应头，浏览器默认优先预览而非触发下载。
• Wagtail/Django配置问题：部署时媒体文件的服务配置不符合下载要求，导致响应头未正确设置。

解决办法 #

1. 处理跨域问题 #

如果媒体文件使用跨域域名：

• 在页面所在域名的响应头中添加Access-Control-Allow-Origin: [媒体文件域名]，同时补充Access-Control-Expose-Headers: Content-Disposition，让浏览器能正确识别download属性。
• 或改用同源域名提供媒体文件服务，彻底规避跨域限制。

2. 给服务器添加下载响应头 #

Nginx配置示例

在媒体文件的location块中添加规则：

location /media/ {
    alias /实际媒体文件存储路径/;
    # 针对指定后缀文件强制触发下载
    if ($request_filename ~* ^.*\.(pdf|jpg|jpeg|png)$) {
        add_header Content-Disposition "attachment";
    }
}

Apache配置示例

在.htaccess或虚拟主机配置中添加：

<FilesMatch "\.(pdf|jpg|jpeg|png)$">
    Header set Content-Disposition "attachment"
</FilesMatch>

3. 用Django视图控制下载行为 #

不想依赖服务器配置的话，可自定义视图处理下载逻辑：

# views.py
from django.http import FileResponse
from wagtail.documents.models import Document
import os

def download_document(request, doc_id):
    doc = Document.objects.get(id=doc_id)
    response = FileResponse(doc.file.open(), as_attachment=True)
    # 自定义下载文件名（可选）
    response['Content-Disposition'] = f'attachment; filename="{os.path.basename(doc.file.name)}"'
    return response

然后在urls.py中添加路由：

# urls.py
from django.urls import path
from .views import download_document

urlpatterns = [
    # 其他路由
    path('download-doc/<int:doc_id>/', download_document, name='download_document'),
]

最后修改模板中的下载链接：

<a href="{% url 'download_document' file.document.id %}" class="text-indigo-600 hover:text-indigo-900" target="_blank">
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-download text-black" viewBox="0 0 16 16">
        <path d="M.5 9.9a.5.5 0 0 1 .5.5v2.5a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2.5a.5.5 0 0 1 1 0v2.5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2v-2.5a.5.5 0 0 1 .5-.5z"/>
        <path d="M7.646 11.854a.5.5 0 0 0 .708 0l3-3a.5.5 0 0 0-.708-.708L8.5 10.293V1.5a.5.5 0 0 0-1 0v8.793L5.354 8.146a.5.5 0 1 0-.708.708l3 3z"/>
    </svg>
</a>

4. 检查Wagtail媒体文件基础配置 #

确保settings.py中的媒体配置正确：

# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

生产环境禁止用runserver直接服务媒体文件，必须通过Nginx/Apache等专业服务器将MEDIA_URL映射到MEDIA_ROOT目录。

内容的提问来源于stack exchange，提问作者Ilian Gion Häsler