django部署静态文件

原创已于 2026-06-14 09:27:54 修改 · 280 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#django

于 2026-06-14 09:26:42 首次发布

这个问题很常见，原因是 Django 在生产模式 (DEBUG=False) 下不会自动处理静态文件。解决的关键在于：通过 collectstatic 命令将 Admin 和 DRF 所需的样式文件集中到 STATIC_ROOT，然后交给容器中的 Web 服务器（如 Nginx）来处理这些文件请求。

以下是两种主流的容器部署解决方案，你可以根据当前架构选择：

方案一：使用 Nginx 容器处理静态文件（推荐生产环境）

这是最标准、最高效的做法。让 Django 专注处理 API 动态请求，Nginx 负责提供 CSS、JS 等静态文件。

1. 修改 Django 配置 (settings.py)
首先配置静态文件的收集路径，并确保 DEBUG 为 False：

DEBUG = False  # 生产环境必须关闭

STATIC_URL = '/static/'
# 容器内收集所有静态文件的最终存放路径
STATIC_ROOT = '/app/staticfiles'

2. 更新 Dockerfile
在构建镜像时，直接运行收集命令，将静态文件打包进镜像：

# Dockerfile
FROM python:3.11-slim
# ... 其他配置

# 运行收集静态文件命令
RUN python manage.py collectstatic --noinput

# 启动命令 (例如使用 Gunicorn)
CMD ["gunicorn", "your_project.wsgi:application", "--bind", "0.0.0.0:8000"]

关键点：--noinput 参数用于自动化，防止构建过程中出现交互提示。

3. 配置 Nginx
在 Nginx 容器的配置文件中，添加一条 location 规则，将 /static/ 的请求直接映射到文件系统，而不要转发给 Django：

server {
    listen 80;
    # 这里设置静态文件请求
    location /static/ {
        # 必须与 Django 的 STATIC_ROOT 路径一致
        alias /app/staticfiles/; 
        expires 30d;
    }

    location / {
        # 将其他请求转发给 Django 应用容器
        proxy_pass http://django_app:8000;
        proxy_set_header Host $host;
    }
}

说明：alias 指令的路径，必须是 Nginx 容器内部能访问到静态文件的路径。

4. Docker Compose 整合
如果你使用 docker-compose.yml，可以将同一个静态文件目录挂载到两个容器，或者直接将文件构建进 Django 镜像并通过卷共享：

services:
  django_app:
    build: .
    volumes:
      - static_volume:/app/staticfiles  # 关键：持久化静态文件

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - static_volume:/app/staticfiles:ro  # 关键：Nginx 只读读取同一份文件
    ports:
      - "80:80"

volumes:
  static_volume:  # 声明共享卷

方案二：临时白嫖 Django 服务（仅调试/非正式环境）

如果你不想配置 Nginx，只是想临时在测试环境（如内网）看下样式，切勿在生产环境使用。

1. 修改 urls.py
仅在 DEBUG 模式下开启静态文件服务，这在容器中同样有效：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # 你的路由...
]

# 仅在开发/调试模式下生效
if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

警告：Django 官方文档明确指出，这种方式 inefficient and insecure（低效且不安全），仅适用于本地开发。

方案三：使用 WhiteNoise （简单省事）

如果你只有一个 Django 容器，不想折腾 Nginx 配置，WhiteNoise 是最佳选择，它能让 Python 代码直接高效地处理静态文件。

1. 安装与配置

pip install whitenoise

# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',  # 建议放在 SecurityMiddleware 之后
    # ...
]

STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
# 可选：启用压缩和缓存支持
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

2. 运行收集命令
和之前一样，确保 collectstatic 被执行了。之后重启容器，/admin/ 应该就有样式了。这种方法通过代码处理静态文件，部署最简单。

常见问题排错

如果按上述步骤操作后依然没有样式，请按以下顺序检查：

确认文件已被收集：进入容器内部查看。运行 docker exec -it <容器名> ls /app/staticfiles，确认里面有 admin/css/base.css 和 rest_framework/css/bootstrap.min.css 等文件。
浏览器缓存：按 Ctrl + Shift + R (或 Cmd + Shift + R) 强制刷新浏览器，清除旧的缓存。
Nginx 路径映射：检查 Nginx 日志 docker logs <nginx容器名> 是否有 404 或 403 报错，确认 alias 路径是否写对。
权限问题：确保 Nginx 容器进程（通常是 www-data 用户）对静态文件目录有 rx（读和执行）权限。