Docker环境下Nginx配置Django静态文件失效问题排查

我查阅了大量同类问题的讨论，仍无法完成Docker环境下Nginx为Django项目提供静态文件服务的配置。日志无报错，访问项目URL时Nginx返回200状态码，直接访问http://127.0.0.1/static/website/style.css可获取静态资源，已清除浏览器缓存，web容器中/opt/django/portfolio/collectstatic目录下也存在静态文件，但页面无法正确加载静态资源。

以下是我的相关配置：

1. settings.py中的静态文件变量设置 #

STATIC_URL = '/static/'
STATIC_ROOT='/opt/django/portfolio/collectstatic'

2. 构建Django项目镜像的Dockerfile #

FROM python:3.11-slim

WORKDIR opt/django/
COPY pyproject.toml .
RUN python -m pip install .

COPY ./portfolio/ ./portfolio/

WORKDIR portfolio/

RUN python manage.py collectstatic --noinput
RUN python manage.py makemigrations
RUN python manage.py migrate

EXPOSE 8000

CMD ["gunicorn", "portfolio.wsgi:application", "--bind", "0.0.0.0:8000"]

3. docker-compose.yml配置 #

services:
  web:
    build:
      context: .
      dockerfile: ./docker/Dockerfile_django
    container_name: webserver
    volumes:
      - static_data:/opt/django/portfolio/collectstatic
    expose:
      - "8000"
    ports:
      - "8000:8000"
    depends_on:
      - db
    networks:
      - docker_network

  db:
    image: postgres:15
    container_name: db_postgres
    expose:
      - "5432"
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    networks:
      - docker_network

  nginx:
    image: nginx:latest
    container_name: nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - static_data:/opt/django/portfolio/collectstatic
    depends_on:
      - web
    networks:
      - docker_network

volumes:
  postgres_data:
  static_data:

networks:
  docker_network:
    driver: bridge
    name: docker_network

4. nginx.conf配置 #

events {}

http {
    server {
        listen 80;
        server_name localhost;

        location /static {
            alias /opt/django/portfolio/collectstatic;
            autoindex on;
        }

        # skip favicon.ico
        location /favicon.ico {
            access_log off;
            return 204;
        }

        location / {
            proxy_pass http://web:8000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

项目结构 #

- my_project/
  - nginx/
    - nginx.conf
  - my_project/
    - my_project/
      - settings.py
      ...
    - web/
      - js/
        - some_js.js
        - some_other_js.js
      - website/
        - style.css
      admin.py
      apps.py
      forms.py
      models.py
      tests.py
      ...

排查方向与可能的配置错误 #

1. Django模板静态资源引用规范 #

检查模板代码：

• 必须在模板顶部添加{% load static %}标签
• 引用静态文件时使用{% static 'website/style.css' %}格式，而非硬编码的/static/website/style.css，确保和Django的STATIC_URL配置匹配
• 确认模板引用路径与collectstatic收集后的实际文件路径一致，比如检查collectstatic/website/style.css是否存在

2. Nginx Location配置细节 #

• location /static使用alias时，避免路径末尾斜杠不一致问题：可修改为location /static/，同时alias路径改为/opt/django/portfolio/collectstatic/;
• 检查Nginx容器内静态文件权限：执行docker exec nginx ls -l /opt/django/portfolio/collectstatic，确保nginx用户有读取权限，必要时在Dockerfile中添加权限设置（如RUN chmod -R 755 /opt/django/portfolio/collectstatic）

3. Django STATICFILES_DIRS配置缺失 #

从项目结构看，静态文件存放在web/目录下，需在settings.py中添加配置，告诉Django收集静态文件的来源：

STATICFILES_DIRS = [
    BASE_DIR / "web",
]

缺失该配置可能导致部分静态文件未被collectstatic收集到STATIC_ROOT中

4. Docker静态文件同步问题 #

• 执行docker-compose down -v删除现有volume，再docker-compose up --build重新构建，避免旧volume数据覆盖新收集的静态文件
• 可将collectstatic移到容器启动时执行，修改Dockerfile的CMD：

CMD ["sh", "-c", "python manage.py collectstatic --noinput && gunicorn portfolio.wsgi:application --bind 0.0.0.0:8000"]

确保每次启动容器都同步最新的静态文件

5. 浏览器端请求验证 #

打开浏览器开发者工具（F12）查看Network标签：

• 确认静态资源请求URL为http://127.0.0.1/static/xxx，检查状态码与响应内容是否正确
• 若状态码为200但页面未加载，排查CSS/JS内部的相对路径引用错误

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