Hyperf Docker 启动失败主因是 php bin/hyperf.php start 未作为 PID 1 运行或监听地址为 127.0.0.1；须改 server.php 中 host 为 0.0.0.0，并确保 docker run 含 -d -p -v -w 四参数及正确镜像与启动命令。
Hyperf Docker 环境启动失败，90% 是因为 php bin/hyperf.php start 没作为 PID 1 运行，或监听地址写成了 127.0.0.1。直接用 docker run -d 启动即可，不用 Supervisor、不用 --watch、不进容器手动敲命令。
docker run 命令必须带这 4 个关键参数
Windows/macOS/Linux 通用，复制粘贴就能跑（路径请按你本地实际调整）：
-
-d：后台运行，别卡在终端里 -
-p 9501:9501：端口映射必须显式写，否则宿主机访问不了 -
-v /your/local/project:/var/www/html：挂载代码目录，路径分隔符用/，Windows 也别用\ -
-w /var/www/html：工作目录必须设对，否则bin/hyperf.php找不到 - 最后跟上启动命令：
php bin/hyperf.php start—— 这才是真正的入口，不是/bin/sh或bash
完整示例（Windows PowerShell）：
docker run -d \ --name hyperf-app \ -p 9501:9501 \ -v E:/my-hyperf:/var/www/html \ -w /var/www/html \ hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6 \ php bin/hyperf.php start
docker-compose.yml 启动时 server.php 配置常被忽略
用 docker-compose up -d 启动却秒退？大概率是 config/autoload/server.php 里没改监听地址。Hyperf 默认是 'host' => '127.0.0.1'，容器内只能本机访问，外部连不上。
- 必须改成
'host' => '0.0.0.0'，否则端口映射白搭 - 检查
'port' => 9501和docker-compose.yml中ports字段一致 - 禁用开发参数：
'pid_file' => '/app/runtime/hyperf.pid'路径要可写，且不要含--watch或--dev - 如果用了
depends_on，务必配condition: service_healthy，不然 MySQL 没起来 Hyperf 就先崩了
启动后访问 404 或 Connection refused 怎么快速定位
别急着重装镜像，先查三件事：
- 容器是否真在运行：
docker ps | grep hyperf，状态必须是Up，不是Exited (1) - 日志里有没有关键报错：
docker logs hyperf-app | tail -20，重点搜Swoole extension not loaded、Permission denied、Address already in use - 容器内能否自己 curl 通：
docker exec hyperf-app curl -v http://127.0.0.1:9501/health，能通说明服务起来了，问题出在宿主机网络或防火墙 - Windows 用户特别注意：Docker Desktop 的文件共享设置里，
E:或D:盘必须勾选启用，否则-v挂载失败但无提示
最易被忽略的点：Swoole 扩展是否真的加载成功。很多镜像标称“含 Swoole”，但实际没启用。进容器执行 php -m | grep swoole，输出为空就说明扩展没生效——这不是 Hyperf 的问题，是镜像构建漏了 docker-php-ext-enable swoole。
