You need to enable JavaScript to run this app. Django结合Nginx、Gunicorn部署时静态文件访问返回404错误
优惠活动
大模型
产品
解决方案
定价
更多

Django结合Nginx、Gunicorn部署时静态文件访问返回404错误

静态文件404问题排查与解决

第一步:定位Nginx端的实际文件缺失

报错日志已经明确标记Nginx查找的目标路径为/blogpy/static/home/test.css,直接进入Nginx运行的容器执行命令验证:

# 进入Nginx容器
docker exec -it <你的Nginx容器名称> sh
# 逐级查看目标目录的文件结构
ls -l /blogpy/static/
ls -l /blogpy/static/home/

通常会出现两种情况:一是目录本身不存在,二是目录下仅包含admin相关的静态文件,缺少home模块的test.css文件。

第二步:修复Docker卷映射的路径不匹配问题

这是当前场景下最核心的根因:

  • 你在宿主机执行collectstatic生成的静态文件,存放在宿主机的blogpy/static目录下
  • Nginx配置里alias指向的是Nginx容器内部的/blogpy/static/路径,如果没有在docker-compose中做宿主机目录到容器目录的映射,这个路径是Nginx容器的独立文件系统,和宿主机生成的静态文件完全不连通
  • 你看到admin静态能正常加载,是因为admin的静态文件被打包到了Gunicorn容器内部,碰巧和Nginx的查找路径有部分重合,属于偶然的正常状态,不是配置正确
    修复方式:在docker-compose的Nginx服务配置块中,添加静态目录的卷映射,把宿主机的静态目录和Nginx配置的路径打通:
# Nginx服务的volumes配置示例
volumes:
  # 格式:宿主机静态目录路径:Nginx容器内的静态目录路径
  - ./blogpy/static:/blogpy/static/

第三步:确保静态文件采集逻辑在正确的运行环境执行

很多人是在本地宿主机执行了collectstatic,但实际Gunicorn运行在独立容器中,容器内的STATIC_ROOT路径和宿主机路径不互通,导致采集的文件根本没有进入运行环境。
需要进入Gunicorn实际运行的Django容器内执行采集命令,保证所有App的静态文件都被汇总到Django配置的STATIC_ROOT路径下:

# 进入Gunicorn运行的Django容器
docker exec -it <你的Django/Gunicorn容器名称> sh
# 无交互执行静态文件采集
python manage.py collectstatic --noinput
# 验证采集结果
ls -l $STATIC_ROOT/home/test.css
# 打印Django识别到的STATIC_ROOT真实路径
python manage.py shell -c "from django.conf import settings; print('STATIC_ROOT实际路径:', settings.STATIC_ROOT)"

根据打印的STATIC_ROOT实际路径,调整docker-compose的卷映射源路径,确保映射给Nginx的目录和STATIC_ROOT是同一个物理位置,避免路径错位。

第四步:修正Nginx配置的语法细节

检查location /static/配置块的写法,规避常见语法坑:

  • alias对应的路径末尾必须加斜杠,否则会出现路径拼接错误
  • 静态文件请求不要配置proxy_pass转发,完全由Nginx本地读取即可,不要把请求转给Gunicorn
  • 可附加静态文件缓存配置,减少重复磁盘读取
    正确的配置块参考:
location /static/ {
    # 路径和Docker卷映射的Nginx容器内路径完全一致,末尾保留斜杠
    alias /blogpy/static/;
    # 静态文件缓存30天
    expires 30d;
}

生效验证

调整完成后,重启Nginx服务、重新访问静态资源地址,确认Nginx错误日志不再报路径不存在的错误,非admin模块的静态文件即可正常加载。

内容的提问来源于stack exchange,提问作者h_python_1368

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.02 10:45:04