Workerman启动报“Workerman不存在”等错误需按序排查：先重装依赖并验证Worker.php存在，再检查PHP函数禁用、端口占用、IP绑定及协议一致性。
Workerman 4.0.41 启动时报“Workerman不存在”、连接被拒绝、段错误或心跳失效，不是框架本身坏了，而是环境配置、权限限制或协议错配触发的连锁反应；必须按顺序验证依赖路径、PHP函数可用性、端口监听状态和客户端协议一致性。
Workerman类未找到：自动加载失效
第一步：进入项目根目录，执行 rm -rf vendor composer.lock 清除残留依赖；这一步必须做，否则旧 autoload 映射会干扰新安装。
第二步：运行 composer install --no-dev -o 重新拉取全部依赖；注意观察终端输出是否包含 workerman/workerman 的安装日志，缺失即失败。
第三步：检查 vendor/workerman/workerman/Worker.php 是否真实存在；【若文件不存在，说明 composer 安装中途被中断或镜像源异常】，需换国内镜像源重试。
第四步：打开 start.php，在 require_once __DIR__ . '/vendor/autoload.php'; 后追加一行：require_once __DIR__ . '/vendor/workerman/workerman/Worker.php';；这是临时兜底方案，仅用于验证是否纯 autoload 问题。
Address already in use：端口被占用
直接运行 netstat -anp | grep :2346（把 2346 换成你实际监听的端口），看是否有进程在 LISTEN 状态。
如果输出里有 php 进程，说明 Workerman 上次没正常 stop，PID 文件丢失了；此时不要盲目 kill -9，先尝试 php start.php stop，它会读取 runtime/pid 目录下残留 pid 文件并优雅退出。
若 stop 命令报错“no pid file”，再执行 ps aux | grep Worker | awk '{print $2}' | xargs kill -9 强杀；【注意：kill -9 是最后手段，会丢失未 flush 的日志和连接状态】。
确认端口空闲后，改用 0.0.0.0:2347 启动测试，排除端口硬编码冲突。
Cannot assign requested address：IP绑定失败
方法一：检查 start.php 中 Worker 构造参数，如 new Worker('websocket://192.168.1.100:2346')；这个 IP 必须是服务器 ifconfig 或 ip a 输出的真实网卡地址，不能填公网 IP 或容器外网 IP。
方法二：直接改成 new Worker('websocket://0.0.0.0:2346')；0.0.0.0 表示监听所有 IPv4 接口，适用于绝大多数部署场景，包括宝塔面板和 Docker 容器。
方法三：腾讯云/阿里云用户特别注意——云服务器的公网 IP 是 NAT 映射地址，不在本机网卡上，所以 bind() 会失败；必须用 0.0.0.0 或内网 IP。
Segmentation fault：底层 C 扩展崩溃
先运行 ulimit -c unlimited 开启 core dump，然后启动服务复现崩溃；没有 core 文件就等于没有病历，没法诊断。
运行 php --ri swoole 查看 Swoole 版本与 PHP 版本是否严格匹配；PHP 8.2 编译的扩展不能跑在 PHP 8.3 上，ABI 不兼容必段错误。
执行 php -i | grep disable_functions，确认输出中不含 pcntl_fork、posix_kill、stream_socket_server；【只要这三个中的任意一个被禁用，Workerman master 进程 fork 子进程时就会触发 SIGSEGV】。
临时注释掉 php.ini 中的 disable_functions 行，重启 PHP-FPM 或 CLI 环境，再试一次启动；若成功，则问题锁定在函数禁用策略。
WebSocket handshake failed：协议不匹配
客户端用 ws://domain.com:2346 连接，服务端必须是 WebSocket 协议；检查 start.php 中 Worker 初始化语句是否为 new Worker('websocket://...')，而不是 http:// 或 tcp://。
如果服务端用了 Webman，确认 config/server.php 里 'type' => 'websocket' 已启用，且未被中间件拦截升级请求。
用 curl 测试基础 HTTP 响应：curl -i http://localhost:2346；返回 400 Bad Request 或 101 Switching Protocols 表示协议层通，返回 Connection refused 则仍是端口或监听问题。
