本质是bind()系统调用失败，需用ss -tuln验证监听状态：无输出=未监听，仅127.0.0.1=仅本机可连，必须改为0.0.0.0并完整重启；同时检查ps aux确认worker进程存在、端口占用及权限限制。

Workerman 4.x 启动时提示 Failed to listen，本质是 PHP 进程调用 bind() 系统调用失败，服务压根没挂起监听。这不是代码逻辑错误，而是系统级资源或配置问题。排查必须跳过日志和控制台输出，直接从操作系统层面验证。

确认监听状态是否真实生效

别信“Start success”，只看内核是否真在监听：

• 执行 ss -tuln | grep :你的端口（如 :2346）
• 无任何输出 → Workerman 完全未监听成功
• 仅显示 127.0.0.1:2346 → 外部设备无法连接，必须改地址
• 显示 *:2346 或 0.0.0.0:2346 → 监听已就位，问题转向防火墙或网络层

检查 Worker 进程是否存活

Master 进程启动不等于服务可用，真正处理连接的是 worker 子进程：

• 运行 ps aux | grep WorkerMan
• 必须看到至少一行含 WorkerMan: worker process
• 若只有 master process，说明 onWorkerStart 中抛出未捕获异常
• 立刻查看 workerman.log 文件末尾，搜索 Fatal error 或 Exception

排查端口占用与绑定冲突

常见干扰源不止是其他服务，还有残留进程和系统限制：

• 查谁占了端口：lsof -i :2346（Linux/macOS），或 netstat -ano | findstr :2346（Windows）
• 若发现旧 Workerman 进程残留（尤其 kill -9 后），手动清理：kill -9 PID 并删除对应 pid 文件
• 端口号 ≤1023？Linux 下普通用户无权绑定，换用 5678、9501 等非特权端口
• Windows 用户注意 Hyper-V 可能预占端口段（如 5000–5099），可用 netsh interface ipv4 show excludedportrange protocol=tcp 查看

验证监听地址与重启方式

写死 127.0.0.1 是最常被忽略的硬伤，且热重载无效：

• 所有 Worker 或 Gateway 实例必须使用 'tcp://0.0.0.0:2346' 或 'tcp://*:2346'
• 改完不能 reload，必须完整重启：php start.php stop && php start.php start
• Docker 环境同理：容器内代码也要监听 0.0.0.0，光靠 -p 2346:2346 不解决根本问题