端口监听失败需先确认Hyperf是否真正监听9501：检查终端日志是否有“[INFO] Worker#0 started.”或“listening at http://0.0.0.0:9501”，无则进程未启动；执行netstat命令验证端口状态，排查port配置为整数、端口占用、Docker映射缺失及proxy_pass地址错配等问题。
端口监听失败：先确认 Hyperf 是否真在监听 9501
Hyperf 启动后没监听到 9501，不是“打不开”，而是压根没 bind 成功。终端日志里没出现 [INFO] Worker#0 started. 或 HTTP server listening at http://0.0.0.0:9501，就别急着查网络或 Nginx——进程根本没起来。
执行以下命令验证：
-
netstat -tuln | grep :9501（Linux/macOS）或netstat -ano | findstr :9501（Windows），无输出 = 没监听 -
php bin/hyperf.php start后立刻看 stdout，是否有Address already in use、failed to listen server port等报错 - 检查
config/autoload/server.php中settings.port是否为整数9501，而非字符串"9501"（Swoole 会静默忽略）
端口被占：用 lsof 定位残留 PHP 进程，别直接 kill -9
最常见原因是上次 php bin/hyperf.php start 没正常退出，或调试器（如 Xdebug）、其他 PHP CLI 服务还挂着。直接 kill -9 可能留下僵尸 worker，反而更难清理。
安全操作顺序：
- 先尝试优雅停止：
php bin/hyperf.php stop（适用于正常启动的守护进程） - 若无效，用
lsof -i :9501查 PID，找到COMMAND列为php且无[worker]后缀的主进程 - 对主进程发信号：
kill -USR2 <pid></pid>（Hyperf 原生支持，会主动关闭所有 worker） - 仍不退出？再试
kill <pid></pid>；仅当ps aux | grep php仍显示该 PID 时，才用kill -9 <pid></pid>
Docker 部署：expose ≠ port mapping，9501 必须显式映射
很多人在 docker-compose.yml 里只写了 expose: -9501，以为宿主机就能访问，结果 telnet 127.0.0.1 9501 连不上——expose 只是内部声明，不对外暴露端口。
必须加 ports 映射：
services:
php:
# ...
ports:
- "9501:9501"
同时确认容器内 Hyperf 监听的是 0.0.0.0:9501（不是 127.0.0.1:9501），可通过容器内执行 ss -tlnp | grep :9501 验证输出是否含 0.0.0.0:9501 或 *:9501。
Nginx 反向代理连不上：proxy_pass 地址必须和容器网络对齐
Nginx 在宿主机，Hyperf 在 Docker，proxy_pass http://127.0.0.1:9501 是错的——它连的是宿主机本机，不是容器。
正确写法取决于网络模式：
- 使用默认 bridge 网络 + 容器名：
proxy_pass http://php:9501;（前提是docker-compose.yml中 service 名为php） - Mac/Win Docker Desktop：
proxy_pass http://host.docker.internal:9501; - Linux 宿主机需手动添加：
docker run --add-host=host.docker.internal:host-gateway ... - 若 Hyperf 监听
0.0.0.0:9501且映射了端口，也可用proxy_pass http://127.0.0.1:9501;，但仅限可信内网
验证前，先在 Nginx 所在机器上执行 curl -v http://php:9501（或对应地址），排除 DNS 和网络层问题。
