Waitress是Windows下Django部署的最优解,因其纯Python实现、天然适配Windows线程模型,避免uWSGI因缺少fork导致的进程僵死、内存泄漏和随机超时;启动须用--listen=0.0.0.0:8000、--threads=4及正确wsgi路径;Nginx需配置Host、X-Forwarded-For、X-Real-IP头,且静态文件必须通过collectstatic收集并由Nginx显式服务。

直接换 Waitress,别碰 uWSGI 或 Apache + mod_wsgi —— 这是 Windows 下 Django 部署慢、卡死、500 错误频发的根源所在。
为什么 uWSGI 在 Windows 上根本不能用
uWSGI 重度依赖 fork() 系统调用,而 Windows 没有这个机制。强行运行会导致:
- 进程僵死(
waitress-serve启动后无响应,tasklist查到进程但不监听端口) - 内存泄漏(反复重启后 RAM 占用持续上涨)
- 随机超时(浏览器等待 15 秒才出现
print("start")日志)
这不是配置问题,是架构不兼容。哪怕你装了 Cygwin 或 WSL,只要目标是原生 Windows 服务,就该绕开 uWSGI。
Waitress 启动命令里最容易漏掉的三个参数
waitress-serve 默认只绑 127.0.0.1:8080,生产部署时外部访问不到,90% 的“能跑但打不开”都卡在这儿:
-
--listen=0.0.0.0:8000:必须写成0.0.0.0,不是localhost或127.0.0.1 -
--threads=4:Windows 不支持--processes,多线程是唯一并发提升手段;建议设为 CPU 核心数 × 2(上限 8) -
myproject.wsgi:application:路径必须指向真实存在的wsgi.py,且该文件中必须定义application变量(Django 默认已生成,但若手动改过wsgi.py可能被删掉)
Nginx 反向代理时转发头缺失的后果
Waitress 不处理 HTTPS、Host 校验或客户端 IP 解析,全靠 Nginx 补足。漏掉以下任意一项,就会触发连锁故障:
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
-
proxy_set_header Host $host;缺失 →request.get_host()返回空,Django CSRF 中间件拒绝请求 -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;缺失 →request.META.get("HTTP_X_FORWARDED_FOR")为空,日志和限流失效 -
proxy_set_header X-Real-IP $remote_addr;缺失 → 所有基于客户端 IP 的逻辑(如白名单、地域判断)全部错乱
这些 header 必须写在 Nginx 的 location / 块内,且不能被其他 proxy_set_header 覆盖。
静态文件没配好,Django 就算跑起来也等于裸奔
Django 的 runserver 自动服务 static/,但 Waitress 完全不管。不处理会直接 404:
- 确保
settings.py中设置了STATIC_ROOT = BASE_DIR / "staticfiles"(注意不是STATIC_URL) - 执行
python manage.py collectstatic --noinput把所有 app 的 static 合并到STATIC_ROOT - Nginx 必须显式配置
location /static/指向该目录,例如:alias /path/to/myproject/staticfiles/;
少一步,CSS、JS、图片全挂,管理后台白屏,用户看到的是裸 HTML。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










