宝塔部署Django项目本质是uWSGI承载应用、Nginx反向代理并服务静态文件，关键需路径、端口、权限三者严格对齐，缺一即导致502或白屏。
宝塔面板部署 Django 项目，本质是让 uWSGI 承载 Django 应用、Nginx 负责反向代理和静态文件服务——不是简单“上传就完事”，关键在三处对齐：路径、端口、权限。错一个，502 或白屏就立刻出现。
确认 Python 项目管理插件已启用且版本匹配
宝塔不会自动识别你的 requirements.txt 是否含 uWSGI，也不会强制安装它。你必须手动确保：uWSGI 在项目虚拟环境里装好了（不是系统 Python 环境）；Python 版本与本地开发一致（比如 3.8/3.9/3.10）；插件设置里选的 Python 解释器路径，要指向你项目实际用的那个虚拟环境的 bin/python。
常见错误现象：
-
ImportError: No module named 'uwsgi'—— 插件用了系统 Python，但uWSGI只装在虚拟环境里 - 项目状态显示“运行中”，但访问返回 502 —— Python 版本不兼容（如 Django 4.x 强制要求 Python ≥3.8）
实操建议：
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
- 进宝塔「软件商店」→「宝塔插件」→ 安装「Python项目管理」（没装的话）
- 添加项目时，“Python版本”下拉框选的是解释器路径，不是版本号字符串；点开右侧“设置”可验证路径是否含
venv或.envs - 上传项目前，在本地执行
pip freeze > requirements.txt，确保含uwsgi==2.0.25（或兼容版本）
uWSGI 配置必须与 Nginx 的 uwsgi_pass 端口/套接字严格一致
宝塔自动生成的 uWSGI 配置默认走 TCP 端口（如 127.0.0.1:8000），但如果你改过配置文件（比如换成 Unix socket），Nginx 却还在用 uwsgi_pass 127.0.0.1:8000，就会直接 502。这不是“大概通就行”的事，是网络层连接失败。
实操建议：
- 进项目「设置」→「配置文件」，检查
socket =行（或http =）—— 若是socket = /www/wwwroot/myproject/uwsgi.sock，Nginx 的location块里必须写uwsgi_pass unix:/www/wwwroot/myproject/uwsgi.sock - 若用 TCP 端口，确保该端口未被其他进程占用：
lsof -i :8000或netstat -tuln | grep :8000 - uWSGI 启动后，检查日志（宝塔项目设置页有“日志”按钮）是否有
bind(): Address already in use或unable to load app
静态文件路径和 Nginx location 规则必须匹配 Django 的 STATIC_URL 和 STATIC_ROOT
宝塔不会自动帮你运行 python manage.py collectstatic。如果只传了源码没收集静态文件，Nginx 就找不到 /static/css/base.css 这类资源，页面无样式、JS 报 404，但后端接口可能完全正常——容易误判为“部署成功”。
实操建议：
- 在宝塔终端里，cd 进项目根目录，执行：
python manage.py collectstatic --noinput - 确认
settings.py中STATIC_ROOT指向的是绝对路径（如/www/wwwroot/myproject/staticfiles），且该目录存在、权限为www:www - Nginx 配置里必须显式声明静态文件规则，不能只靠
location /转发给 uWSGI：location /static/ { alias /www/wwwroot/myproject/staticfiles/; } - 如果前端请求路径带前缀（如
/api/v1/login），Django 的ROOT_URLCONF和 Nginx 的location /api/必须对齐，否则路由 404
Django 的 ALLOWED_HOSTS 和跨域配置必须包含真实访问地址
哪怕 Nginx 和 uWSGI 全通，ALLOWED_HOSTS = ['*'] 在生产环境会被 Django 直接拒绝请求（HTTP 400 Bad Request）。而 CORS 配置写错，前端调接口会卡在预检（OPTIONS）阶段，控制台报 “No 'Access-Control-Allow-Origin' header”。
实操建议：
-
ALLOWED_HOSTS里填服务器公网 IP、域名，不要留空或只写localhost；多个用英文逗号分隔：['7.123.15.134', 'myapp.com'] - 如果前端和后端不同源（比如前端跑在
http://localhost:3000），必须装django-cors-headers并配置CORS_ALLOWED_ORIGINS，不是只开CORS_ORIGIN_ALLOW_ALL - 检查
settings.py是否漏掉'corsheaders.middleware.CorsMiddleware'加入MIDDLEWARE列表顶部 - 浏览器 F12 → Network 标签页，看请求响应头是否有
Access-Control-Allow-Origin，没有就是中间件没生效
最常被跳过的一步：改完 settings.py 或 uWSGI 配置后，必须在宝塔项目页点「重启」，而不是只刷新网页。uWSGI 进程不重载，所有改动都只是文件，不会生效。
