Ubuntu22+Gunicorn+Nginx部署Wagtail后静态资源加载异常求助

1. 确认Django已执行静态文件收集 #

Wagtail基于Django，必须先把所有app的静态文件集中到统一目录，执行以下命令：

python manage.py collectstatic

记住命令输出的目标目录（比如/var/www/your_project/static/），后续Nginx要指向这个路径。如果没执行过或新增资源后没重新收集，直接会导致资源缺失。

2. 检查静态资源目录权限 #

确保Nginx进程（默认属组www-data）能读取静态文件：

# 递归设置目录归属和权限
sudo chown -R www-data:www-data /var/www/your_project/static/
sudo chmod -R 755 /var/www/your_project/static/

权限不足的话，Nginx会返回403错误，浏览器根本拿不到文件。

3. 验证Nginx的静态资源路由配置 #

打开站点的Nginx配置文件（一般在/etc/nginx/sites-available/your_project），确认静态资源转发规则正确，示例片段：

server {
    # 其他配置（监听端口、SSL等）...

    location /static/ {
        alias /var/www/your_project/static/;
        # 可选：添加缓存头优化加载速度
        expires 30d;
        add_header Cache-Control "public, max-age=2592000";
    }

    location /media/ {
        alias /var/www/your_project/media/;
        expires 30d;
        add_header Cache-Control "public, max-age=2592000";
    }

    # Gunicorn转发规则
    location / {
        proxy_pass http://unix:/run/gunicorn.sock; # 也可以是http://127.0.0.1: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;
    }
}

注意：alias后面的路径必须以/结尾，和location的/static/对应，否则会出现路径拼接错误。修改后重启Nginx生效：

sudo nginx -t && sudo systemctl restart nginx

4. 核对Django settings.py配置 #

确认settings.py里的静态资源参数正确：

DEBUG = False # 生产环境必须设为False，否则Django会自行处理静态资源，和Nginx冲突
STATIC_URL = '/static/'
STATIC_ROOT = '/var/www/your_project/static/' # 和collectstatic的目标目录一致
MEDIA_URL = '/media/'
MEDIA_ROOT = '/var/www/your_project/media/'

如果DEBUG设为True，生产环境下Django不会使用STATIC_ROOT的资源，直接从app的static目录读取，这在Nginx+Gunicorn部署下必然出问题。

5. 查看浏览器控制台错误信息 #

按F12打开开发者工具，切换到Network标签刷新页面，看静态资源的请求状态：

• 404：Nginx找不到文件，检查路径是否正确、collectstatic是否执行
• 403：权限问题，回头检查目录权限
• 500：Nginx配置有误，查看错误日志：sudo tail -f /var/log/nginx/error.log
• 混合内容错误：页面是HTTPS但静态资源请求HTTP，浏览器会拦截，要确保所有资源请求用HTTPS

6. 确认mime.types文件完整性 #

虽然你已经加了include /etc/nginx/mime.types;，可以检查文件是否包含常见静态资源类型：

cat /etc/nginx/mime.types | grep -E "(css|png|jpg|jpeg|gif)"

如果缺少对应类型（比如.css的text/css），可以在Nginx的静态资源location里手动补充：

location /static/ {
    alias /var/www/your_project/static/;
    types {
        text/css css;
        image/png png;
        image/jpeg jpg jpeg;
        # 其他需要的类型
    }
}

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