Hyperf定时任务本身不监听端口，报“Address already in use”实为HTTP Server（如9501）、Async Queue消费者或残留进程占用端口所致；应先用lsof -i :9501定位PID，优先kill -USR2优雅终止，无效再kill，避免直接kill -9。
Hyperf 定时任务本身不监听端口，但常因关联服务（如 HTTP Server、Async Queue 消费者、Task Worker）或残留进程导致端口冲突。真正被占的不是“定时任务端口”，而是它所依赖的主服务端口（如 9501）或 Redis/MySQL 等配套服务端口。
先确认是不是定时任务真在占端口
Hyperf 的 定时任务由 CronProcess 承载，它不绑定网络端口。如果你启动定时任务时报“Address already in use”，问题一定出在别处：
- 你同时启用了 HTTP Server（默认 9501），而该端口已被占用
- 项目里还注册了 AsyncQueueProcess 或其他网络型进程，它们会主动监听或连接外部服务
- 上一次启动未正常退出，遗留了 master 进程或 worker，仍在监听原端口
- 定时任务中调用了本地 HTTP 客户端、Redis 或 MySQL，并且这些连接池配置不当，引发连接堆积或假性端口占用（如 Redis 绑定本地 6379 失败）
快速定位真实占用进程
别猜，直接查：
- Linux/macOS：运行 lsof -i :9501（把 9501 换成你报错的实际端口），看 PID 和 COMMAND
- Windows：以管理员身份运行 netstat -ano | findstr :9501，再用 tasklist | findstr "PID" 查进程名
- 若提示 lsof 未安装：macOS 用 brew install lsof；Ubuntu/Debian 用 sudo apt install psmisc（含 fuser）
重点关注输出中是否出现 php、hyperf、redis-server、mysqld —— 这些才是真凶。
安全清理残留进程
找到 PID 后，按优先级操作：
- 如果是 Hyperf 主进程（COMMAND 显示 php 且无 [worker] 后缀），先发优雅信号：kill -USR2 PID
- 若无响应，再用 kill PID（TERM 信号）
- 仅当进程僵死（ps aux | grep php 仍显示它），才用 kill -9 PID
- 如果查到多个 PID（如 master + 几个 worker），通常只杀主进程即可，其余会自动退出
避免下次再冲突的实操建议
定时任务场景下，最易复发的问题是开发时反复 start/stop 导致残留。推荐这几招：
- 每次启动前加检测脚本：在项目根目录放一个 check-port.sh，内容为 lsof -i :9501 && echo "Port occupied!" || echo "Port free"
- 改用非默认端口开发：修改 config/autoload/server.php 中的 port 值（如改为 9502），避开常见冲突
- 确保 CronProcess 不与 HTTP Server 共用同一份配置异常——检查 processes.php 是否误注册了重复进程类
- 若用 Docker 运行，注意宿主机端口映射是否与其他容器或本地服务重叠，执行 docker ps 确认
