uwsgi启动Django时静态文件404或白屏，如何正确配置static和media？

Question

**问题描述（198字）：** 使用 uWSGI 部署 Django 时，常出现静态文件（CSS/JS/IMG）返回 404 或页面白屏，根本原因在于 uWSGI 默认**不处理静态资源**，而 Django 开发服务器（`runserver`）才内置 `staticfiles` 服务逻辑。生产环境必须由 Web 服务器（如 Nginx）或显式配置的 uWSGI 内置静态路由来提供 `/static/` 和 `/media/` 路径。常见错误包括：未在 `settings.py` 中正确设置 `STATIC_ROOT` 并执行 `collectstatic`；uWSGI 配置遗漏 `static-map` 或 `static-all` 指令；Nginx 未配置对应 location 块代理静态路径；或 `DEBUG=False` 时 Django 自动禁用 `runserver` 的静态服务但未补位。此外，`MEDIA_URL` 与 `MEDIA_ROOT` 权限、路径映射错误，也会导致用户上传文件无法访问。需严格区分开发与生产静态资源交付链路——uWSGI 只负责动态请求，静态资源必须交由前置 Web 服务器或 uWSGI 显式托管。

Answer 1

```html

一、现象层：静态资源 404 与白屏的表征诊断

• 浏览器开发者工具 Network 面板中，/static/css/app.css、/media/uploads/avatar.jpg 等请求返回 404 Not Found；
• HTML 渲染正常但样式/脚本未加载 → 页面无样式、交互失效、JS 报错（如 Uncaught ReferenceError）；
• uWSGI 日志中无对应静态路径访问记录（印证其未介入处理）；
• DEBUG=True 时页面正常，切为 False 后立即白屏 —— 典型开发/生产行为割裂信号。

二、配置层：Django 核心静态资产管线校验

必须完成三要素闭环：

配置项	典型错误值	生产推荐值
STATIC_URL	'/static/'（正确）但未配套映射	'/static/'（保持一致）
STATIC_ROOT	os.path.join(BASE_DIR, 'static')（源目录，❌）	os.path.join(BASE_DIR, 'collected_static')（目标收集目录，✅）
MEDIA_URL/MEDIA_ROOT	MEDIA_ROOT = '/var/www/myapp/media'（权限不足或路径不可写）	MEDIA_ROOT = '/opt/myapp/media' + chown www-data:www-data /opt/myapp/media

执行：python manage.py collectstatic --noinput --clear，验证输出文件数 ≥ STATICFILES_DIRS 总和。

三、部署层：uWSGI 静态路由双模式深度解析

uWSGI 提供两种静态托管机制，适用场景迥异：

• 模式① static-map（精准路径映射）：--static-map /static=/opt/myapp/collected_static —— 推荐，粒度可控、支持缓存头；
• 模式② static-all（全量目录托管）：--static-all /opt/myapp/collected_static —— 仅限调试，不区分 URL 前缀，易引发安全风险；
• ⚠️ 注意：static-map 必须在 uWSGI 配置中置于 module 和 callable 之后，否则被忽略。

四、网关层：Nginx 静态服务黄金配置范式

location /static/ {
    alias /opt/myapp/collected_static/;
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}
location /media/ {
    alias /opt/myapp/media/;
    expires 7d;
    add_header Content-Disposition "inline";
}

关键点：alias 末尾斜杠必须与 location 末尾斜杠严格匹配；root 会拼接路径，alias 直接替换，误用将导致 403/404。

五、权限与生命周期：从文件系统到 HTTP 流程链路

graph LR
  A[用户请求 /static/base.css] --> B{Nginx 匹配 location /static/}
  B -->|命中| C[Nginx 查找 alias 指向路径]
  C --> D[检查文件是否存在 & www-data 是否有读权限]
  D -->|是| E[返回 200 + Content-Type:text/css]
  D -->|否| F[返回 404 或 403]
  B -->|未命中| G[uWSGI 接管 → Django 尝试 findstatic → 失败 → 404]

六、进阶陷阱：MEDIA_ROOT 的容器化与 SELinux 约束

• Docker 中挂载 -v ./media:/opt/myapp/media 时，宿主机文件 uid/gid 可能与容器内 www-data 不匹配 → 使用 chown -R 33:33 media/（Debian 系 www-data UID=33）；
• RHEL/CentOS 启用 SELinux 时需添加上下文：chcon -Rt httpd_sys_rw_content_t /opt/myapp/media；
• collectstatic 若使用 --link 参数，在 NFS 或容器共享卷上将失败，必须禁用。

```