Hyperf单机部署端口冲突本质是目标端口（如9501）被其他进程占用，需先用lsof或netstat定位PID和COMMAND，优先kill -USR2优雅终止Hyperf主进程，再验证端口是否释放（无输出且curl返回Connection refused），最后启动服务。
Hyperf单机部署时端口冲突报错，本质是目标端口（默认 9501）已被其他进程占用，不是配置写错，而是系统层面“有人先占了座位”。快速解决的关键在于：**准确定位是谁占着、安全清理它、再验证是否真空闲**。
查清楚谁在用这个端口
先确认具体报错端口（比如日志里写的是 Address already in use: 0.0.0.0:9501，那就查 9501）。执行：
-
lsof -i :9501（macOS / Linux 有 lsof） - 若提示
command not found，macOS 装：brew install lsof；Ubuntu/Debian：sudo apt install psmisc（可用fuser -n tcp 9501）；CentOS/RHEL：sudo yum install psmisc - 或通用命令：
netstat -tulnp | grep :9501
输出里重点关注 PID 和 COMMAND 列——如果看到 php 或 hyperf，大概率是上次没关干净的残留进程；如果是 node、java 或调试工具（如 Xdebug 监听），也得一并处理。
优先软杀，别急着 -9
找到 PID 后，别第一反应就 kill -9。Hyperf 的主进程支持优雅退出：
- 对主进程 PID（COMMAND 是
php且没带[worker]后缀的那个）发信号：kill -USR2—— Hyperf 会主动关闭所有 worker 并退出 - 不行再试：
kill（发送 TERM 信号，多数能正常收尾） - 只有当
ps aux | grep php还显示该进程、且无响应时，才用kill -9
如果 lsof 显示多个 PID（主进程 + 几个 worker），通常只杀主进程即可，其余会自动退出。
启动前快速验证端口是否真正空闲
杀完别马上启动，先验证端口是不是真释放了：
- 再次运行
lsof -i :9501或netstat -tuln | grep :9501，应无任何输出 - 本地测试连通性：
curl -v http://127.0.0.1:9501，如果返回Connection refused，说明端口已空——这是理想状态；如果卡住或超时，可能是防火墙拦截，需检查 iptables / ufw / SELinux
确认空闲后，再执行 php bin/hyperf.php start。开发中临时避让，可直接改 config/autoload/server.php 里的 port 值为 9502 等未被占用端口。
避免下次再撞车的小习惯
端口冲突反复发生，往往是因为操作不规范：
- 启动服务时加
&或用nohup php bin/hyperf.php start > /dev/null &，防止终端关闭导致进程异常退出后残留 - 养成停服务习惯：
php bin/hyperf.php stop比手动 kill 更可靠 - 多人共用一台开发机？约定好各自项目端口范围（如 A 用 9501–9505，B 用 9506–9510），减少交叉占用
