WebSocket连接失败主因是ASGI配置缺失：需确认asgi.py存在且正确配置ProtocolTypeRouter、settings中设置ASGI_APPLICATION、启动时用daphne或runserver并确保channels在INSTALLED_APPS中。
WebSocket连接被拒绝：Django Channels的ASGI配置漏了
本地开发时 WebSocket connection to 'ws://127.0.0.1:8000/ws/chat/' failed，大概率不是前端代码问题，而是 ASGI 服务根本没跑起来。Django 默认用 WSGI，Channels 要求必须切换到 ASGI 模式。
- 确认项目根目录有
asgi.py，且内容已按 Channels 文档生成（含ProtocolTypeRouter和URLRouter） -
settings.py中必须有ASGI_APPLICATION = 'myproject.asgi.application'，不能写成WSGI_APPLICATION - 启动命令必须是
daphne -b 127.0.0.1 -p 8000 myproject.asgi:application或python manage.py runserver（仅限开发，需确保daphne和channels已安装） - 如果用
runserver却看到Starting development server at http://127.0.0.1:8000/而没提WebSocket，说明 Channels 未生效——检查是否在INSTALLED_APPS里加了'channels'
消费者接收不到消息：Group name 拼写或作用域不一致
前端发了消息，后端 ChatConsumer.receive() 能触发，但其他客户端收不到，常见原因是 Group 名称没对上。Channels 的 group_send() 不会报错，发错了就静默丢弃。
- 确保
self.channel_layer.group_add("chat_room", self.channel_name)和self.channel_layer.group_send("chat_room", {...})中的字符串完全一致（区分大小写、无空格） - Group name 不能含点号
.、星号*等特殊字符；推荐只用字母、数字、下划线 - 如果聊天室按 URL 参数动态命名（如
/ws/chat/{room_id}/），必须在connect()中解析self.scope['url_route']['kwargs']['room_id']并拼出 group name，不能硬编码 - 注意
group_add是异步操作，建议加await并捕获异常：await self.channel_layer.group_add(group_name, self.channel_name)
消息乱序或重复：缺乏消息序列号和去重逻辑
多人高频发送时，用户可能看到自己刚发的消息出现在历史记录里两次，或收到顺序错乱。Channel Layer（如 Redis）本身不保证消息全局有序，也不自动去重。
Django Unfold
下载
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
- 前端发送消息时，建议附带唯一客户端 ID（如
uuid4()）和时间戳，后端存入数据库时一并记录 - 广播前先入库再发
group_send，避免“先发后存”导致离线用户重连后拉不到这条消息 - 若需严格顺序，不要依赖 Channel Layer 的投递顺序；改用数据库主键或自增字段排序，前端按
id渲染 - Redis 作为 backend 时，
GROUP模式不适用；Channels 的channel_layer.group_send是「尽力而为」，不提供 ACK 机制
生产环境部署失败：Daphne + Nginx WebSocket 升级头缺失
上线后 WebSocket 握手返回 400 或直接断开，Nginx 日志里出现 "Connection: upgrade" header is missing，这是反向代理没透传 WebSocket 协议头。
- Nginx 配置中，
location /ws/块必须显式设置：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade"; - Daphne 必须监听内网地址（如
-b 127.0.0.1），不能暴露给公网；Nginx 才是面向用户的入口 - 检查
settings.py中CHANNEL_LAYERS是否指向真实 Redis 实例（非locmem），否则多进程下 Group 消息无法跨 worker 传递 - 如果用 Supervisor 管理 Daphne 进程，确保
autostart=true且 stdout_logfile 路径可写，否则启动失败却无提示
WebSocket 的状态管理比 HTTP 复杂得多：连接生命周期、断线重连策略、消息幂等性、水平扩展时的 Channel Layer 选型——这些都不是 Channels 文档里几行代码能覆盖的。真正卡住人的，往往在 group name 拼错一个下划线，或者 Nginx 少了一行 proxy_set_header。
