Django 在 DEBUG=False 的生产环境中，不会自动提供 media 静态资源服务；若未配置 Web 服务器（如 Nginx/Apache）托管 MEDIA_ROOT，所有 /media/ 请求将返回 404。
django 在 `debug=false` 的生产环境中，不会自动提供 media 静态资源服务；若未配置 web 服务器（如 nginx/apache）托管 `media_root`，所有 `/media/` 请求将返回 404。
这是一个在 Django 部署中极为常见却容易被误解的问题：本地开发一切正常，上线后所有用户上传的图片、PDF 等 media 文件全部 404，而错误日志或浏览器 Network 面板仅显示 Failed to load resource: the server responded with a status of 404 (Not Found) —— 这并非路径写错、文件丢失或模板引用错误，而是 Django 主动拒绝处理 media 请求 的设计行为。
根本原因：Django 的安全设计机制
Django 明确规定：static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) 仅在 DEBUG=True 时生效（见 Django 官方文档）。当 DEBUG=False（生产环境强制要求），该 URL 配置会被静默忽略，Django 不再响应任何 /media/ 开头的请求，Web 服务器（如 Nginx）若未显式配置 media 路由，则直接返回 404。
⚠️ 注意：修改 Google Analytics 标签位置（如误放
外）不会导致 media 404。该操作可能引发 HTML 结构错误或 JS 执行异常，但绝不会干扰媒体文件路由——这是一个典型的“时间巧合”误导。真正触发问题的，是部署时意外将 DEBUG 设为 False，却未同步配置 Web 服务器接管 media 服务。
正确解决方案：交由 Web 服务器托管 Media
✅ 推荐方案（Nginx 示例）
在站点配置中（如 /etc/nginx/sites-available/your-site）添加 location 块：
location /media/ {
alias /path/to/your/project/media/; # 注意末尾斜杠必须与 MEDIA_URL 一致
expires 1h;
add_header Cache-Control "public, immutable";
}✅ 关键点：
- 使用 alias（非 root），且 alias 路径必须以 / 结尾；
- alias 指向的是 MEDIA_ROOT 的绝对物理路径（如 /opt/myproject/media/），而非相对路径；
- 确保 Nginx 用户（如 www-data）对该目录有读取权限：sudo chown -R www-data:www-data /path/to/media/。
✅ Apache 替代方案（启用 mod_alias）
Alias /media /path/to/your/project/media
<Directory "/path/to/your/project/media">
Require all granted
Options FollowSymLinks
</Directory>开发 vs 生产：配置分离最佳实践
永远不要在生产环境设置 DEBUG=True 来“修复”此问题——这会暴露敏感调试信息、禁用安全中间件（如 SECURE_BROWSER_XSS_FILTER），并带来严重安全隐患。正确的做法是：
- 开发环境（DEBUG=True）：保留 urlpatterns += static(...)，方便快速迭代；
-
生产环境（DEBUG=False）：
- 移除 static() 动态 URL 配置；
- 由 Nginx/Apache 托管 /media/ 和 /static/；
- 使用 python manage.py collectstatic 集中管理静态资源（STATIC_ROOT）；
- MEDIA_ROOT 保持独立，专用于用户上传内容。
验证步骤（快速排障）
- 检查 settings.py：确认 DEBUG=False 且 MEDIA_ROOT 是绝对路径；
- 检查 Web 服务器配置：curl -I https://yoursite.com/media/test.jpg 应返回 200 OK；
- 检查文件权限：ls -l $(python -c "from django.conf import settings; print(settings.MEDIA_ROOT)")；
- 查看 Web 服务器错误日志（如 /var/log/nginx/error.log），定位 404 具体原因。
总结
Django 的 media 404 并非代码缺陷，而是其“生产就绪”设计的必然体现。真正的解决路径只有一条：放弃让 Django 自行服务 media 文件，转而交由专业 Web 服务器高效、安全地完成这一职责。这既是性能优化（减少 Python 进程 I/O 压力），更是安全加固（避免调试接口暴露、路径遍历风险）。每一次因 DEBUG=False 引发的 404，都是 Django 在提醒你：生产环境，请交出控制权。
