如何在宝塔面板部署Django项目？配置uWSGI与Nginx实现生产环境运行-php教程-PHP中文网

宝塔部署django项目本质是uwsgi承载应用、nginx反向代理并服务静态文件，关键需路径、端口、权限三者严格对齐，缺一即导致502或白屏。

如何在宝塔面板部署django项目？配置uwsgi与nginx实现生产环境运行

宝塔面板部署 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

提供使用 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，没有就是中间件没生效