至于故事的开始，一切都在 TestClient 里完美运行

写完 WS 接口的当天晚上。我兴奋地跑了自己写的 _debug_ws.py 自测脚本：

 尝试真正的 WebSocket 握手 + ping-pong + chat：
✅ 握手成功： Switching Protocols
✅ ping -> pong
✅ 收到 start 帧
✅ 收到 done 帧
✅ 收到 个chunk，总字符数:
最终状态 start=True done=True → 🎉 WS链路完全正常!

漂亮！_debug_ws.py 的路由表打印里也明明白白写着：

 /api/v1/sse/chat methods={'POST'}
/api/v1/ws/chat/{session_id} methods={'WS'}

路由注册了自测通过了发布到 uvicorn，肯定没问题吧？

说到第一锅，甩给 iOS 模拟器网络隔离

第二天把 Flutter 客户端跑起来控制台无情打脸：

 ❌ 连接失败: WebSocketException:Connection to 'http://.:/.../demo_session_001#' was not upgraded to websocket。HTTP status code:

痛点： iOS 模拟器自带网络隔离，让它只能访问自己的域名“.”而不是宿主机。

• 把后端启动参数加了 —host .
• ifconfig bridge100 拿到 Mac 的桥接 IP “.”
• 把 Flutter 里的 host 换成真实 IP

再跑一遍，还是失效。

从第二锅来看。甩给 FastAPI 路由注册顺序 + include_router 漏加

痛点： 假设所有都配置正确，却仍然 404。

I started suspecting backend but my test script succeeded—***?

• "是否在 create_app 工厂函数里漏掉了 include_router?" — 已确认添加，
• "同方法 HTTP GET 路由抢占 WS Upgrade?" — 未发现同名 GET。
• "多 worker 模式下子进程未初始化?" — 单 worker 重启依旧。
• "URL prefix 拼错?" — 正确为 /api/v1 + /ws/chat/{session_id}。

I fetched openapi.json:

{
"paths": {
"/api/v1/sse/chat": { "post": { ... } },"/health": { "get": { ... } }
// ❌ /api/v1/ws/chat/{session_id} 不见了！}
}

真相揭晓这方面，我没装 WebSocket 协议库

I added a debug log in create_app:

print}")
for r in app.routes:
print.name}: {getattr}")

The uvicorn restart showed no APIWebSocketRoute:

 app.routes 列表长度:
- APIRoute: /api/v1/sse/chat
- APIRoute: /health
... 

The same create_app used in _debug_ws.py printed route correctly because TestClient uses httpx which implements its own WebSocket protocol.

I ran:

 % pip list | grep -E 'websockets|wsproto'

I installed it:

 % pip install websockets
% uvicorn app:app --reload

app.routes 列表长度: - APIRoute: /api/v1/sse/chat - APIWebSocketRoute: /api/v1/ws/chat/{session_id} ...

Curl handshake succeeded:

为什么 TestClient 能通？为什么是静默失败，老实说，

✔ User-friendly test client uses httpx's built-in WS implementation,so routes are always found.

❌ User-facing server relies on external libs . If missing。FastAPI silently drops @websocket routes without error.

SSE works because it’s pure HTTP and doesn’t depend on those libs.

最終避坑 Checklist

步骤
命令/检查点	不通过时处理
- 检查 websockets/wsproto 是否已安装

---