这是端口被占用导致的启动失败，而非Hyperf自身错误；需先执行php bin/hyperf.php stop优雅关闭，再用lsof或netstat查PID确认是否为残留Hyperf或其他服务（如redis、node）占用，开发时可临时修改server.php端口验证。
failed to listen server port [0.0.0.0:9501], Error: Address already in use [98] 是什么
这不是 Hyperf 本身出错，而是操作系统拒绝绑定端口——9501 已被某个进程监听。常见于开发时反复启停服务后残留 worker 进程、Xdebug（如监听 9003）误占、或本地跑着 Redis/Node/Java 服务。别急着 kill -9，先确认是不是上一次没关干净的 Hyperf 自己。
php bin/hyperf.php stop 不生效怎么办
Hyperf 的 stop 命令依赖 manager 进程正常响应。如果它已僵死或未启动，该命令会卡住或静默失败。
- 执行
php bin/hyperf.php stop后无输出、不返回 shell，说明 manager 进程可能已退出或异常 - 此时直接查端口更可靠：用
sudo lsof -i :9501 -P -n或netstat -tulnp | grep :9501 - 若输出中
COMMAND列是php且用户是你自己，大概率就是残留的 Hyperf worker - 若看到
redis-server、node、java或phpstorm，说明是其他服务占了——别乱 kill，先看场景是否合理
lsof 查不到进程但端口仍被占？注意 LISTEN 状态过滤
lsof -i :9501 可能返回空，但服务还是起不来。这是因为默认会列出所有连接状态（包括 ESTABLISHED），而真正“占端口”的只有处于 LISTEN 状态的进程。
- 精准查监听者：用
sudo lsof -iTCP -sTCP:LISTEN -P -n | grep :9501 - Mac 用户可省略
sudo（部分版本权限宽松），但麒麟/Ubuntu/CentOS 通常需要 - 如果系统没装
lsof（如精简版麒麟 V10），先运行lsof -v验证；缺失则按发行版装：sudo apt-get install lsof或sudo yum install lsof - 查完 PID 后，优先发
kill（不带-9），等几秒再试启动；仅当进程无响应时才用sudo kill -9 PID
kill -9 之后 lsof 还显示端口占用？可能是 TIME_WAIT
执行 kill -9 PID 后立刻 lsof -i :9501 仍有输出，不等于端口真被占着。Linux 内核在 TCP 关闭后会保留 socket 在 TIME_WAIT 状态约 60 秒，这是正常行为。
- 用
ss -tuln | grep :9501替代lsof查看真实监听状态：如果只显示State: TIME-WAIT或根本无输出，说明端口实际已空闲 - Hyperf 启动时自动启用
SO_REUSEADDR，能复用处于TIME_WAIT的端口，所以通常不用等 - 如果反复出现
Address already in use，重点检查代码里是否漏调socket_close()或fclose()，而非怪端口没释放完
真正容易被忽略的是 Xdebug 监听端口和 Docker 容器端口映射冲突——它们不会出现在 php 进程名里，但一样会抢 9501 或相邻端口。查的时候别只盯着 COMMAND 是不是 php，要看清楚 PID 对应的完整命令行（可用 ps -p PID -f 补查）。
