Yii框架本身不内置WebSocket支持，必须用Swoole、Ratchet等外部常驻进程独立承载；因PHP-FPM为同步阻塞模型，在控制器中new Swoole\WebSocket\Server会阻塞进程导致504超时，正确做法是通过CLI命令启动脱离Web上下文的WebSocket服务。
Yii 框架本身不内置 WebSocket 服务支持，直接在 Web 请求中启动 WebSocket 服务器会阻塞 PHP-FPM 进程；必须用外部常驻进程（如 Swoole、Ratchet）独立承载，再与 Yii 应用通过共享存储或事件总线协同。
为什么不能在控制器里 new Swoole\WebSocket\Server()
PHP-FPM 是同步阻塞模型，每个 HTTP 请求独占一个 worker 进程。一旦你在 action 里执行 new Swoole\WebSocket\Server()，它会立即接管当前进程并进入事件循环——后续的 echo、return 全部失效，Nginx 返回 504 或超时白屏。
- 错误现象：页面卡死、日志出现
PHP Warning: event_base_loop(): no events registered或max_execution_time exceeded - 正确位置：只能放在 CLI 脚本中，例如
yii websocket/start命令行入口 - 别指望
yii\web\Controller承担长连接逻辑——它的生命周期是毫秒级的，不是分钟级的
Swoole 方案：绕过 Yii 生命周期启动服务
你得写一个脱离 Web 上下文的启动脚本，手动加载 Yii 配置但不走路由分发。Swoole 实例要自己管理连接池、广播逻辑，不能依赖 Yii 的组件自动注入。
- 创建
commands/WebSocketCommand.php，继承yii\console\Controller - 在
actionStart()中初始化Swoole\WebSocket\Server，监听端口（如9501） - 连接建立后，用
$server->connections或自定义数组维护客户端列表，不要依赖Yii::$app->user——此时无 session、无 identity - 消息广播需自行实现：遍历所有活跃连接调用
$fd->push()，Yii 的Event组件在这里基本用不上 - 若需访问数据库或缓存，用
Yii::$app->db或Yii::$app->cache是安全的，但注意连接复用和超时设置
Ratchet 方案：用 Composer 加载后独立运行
Ratchet 更轻量，适合快速验证，但它和 Yii 完全解耦——你无法在 onMessage() 回调里直接调用 Yii::$app->mailer 或触发 ActiveRecord 事件，必须显式引入或封装。
- 安装后新建
websocket-server.php（不在web/目录下），内容为纯 PHP 启动脚本 -
IoServer::factory()的第二个参数是端口，第三个是WebSocket实例，该实例必须实现MessageComponentInterface - 在
onMessage()中解析 JSON 后，若需查用户数据，应手动 new Model 或调用 DAO 层，避免尝试Yii::createObject()初始化复杂组件 - 别把 Ratchet 服务和 Nginx 放同一端口；建议反向代理 WebSocket 流量到
ws://yourdomain.com/ws→localhost:8080
前端怎么连？别信“自动识别 Yii 环境”这种说法
浏览器 WebSocket 构造函数只认 URL，和后端用什么框架无关。你配错协议、端口或跨域头，前端就报 net::ERR_CONNECTION_REFUSED 或 failed: Error during WebSocket handshake。
- 确保服务端响应了正确的
Upgrade: websocket和Connection: Upgrade头（Swoole 默认有，Ratchet 需确认HttpServer包裹） - Nginx 必须添加 WebSocket 支持配置：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; - 前端连接地址必须带
ws://或wss://，不能写成http://；Yii 的Yii::getAlias('@web')对这里完全没用 - 用户身份绑定靠消息体传
token或user_id，服务端收到后查库验证——没有“Yii 登录态自动透传”这回事
最易被忽略的一点：WebSocket 连接是双向、无状态的，但 Yii 的设计哲学是请求-响应、有状态（session）。两者底层模型冲突，硬凑会导致内存泄漏、连接堆积、广播错乱。接受这个事实，用清晰的边界（CLI 进程 + Web API + 前端桥接）比强行“集成”更可靠。
