第一反应是查日志而非重跑容器；执行docker ps -a找Exited非零码容器，用docker inspect看ExitCode和Error，再用docker logs读stdout/stderr定位报错，若提示“No such container”则说明创建失败，需检查run命令输出。
Hyperf 容器启动失败，第一反应不是删容器重跑，而是盯住日志——它直接告诉你进程卡在哪一步。
先确认容器是否真“启动过”
很多情况是容器秒退，你以为没起来，其实它已经跑了一次又挂了。执行：
-
docker ps -a：找状态为
Exited (1)或类似非零退出码的容器 -
docker inspect 容器名：重点看
State.ExitCode和State.Error字段，有些错误会直接写在这里（比如配置路径不存在）
立刻查 stdout/stderr 输出
Hyperf 启动报错基本都打在标准输出里，用 docker logs 直接读取：
- docker logs 容器名：看全部日志，适合刚退出、日志不长的情况
- docker logs --tail 50 容器名：聚焦最后 50 行，快速定位最后一句报错
-
docker logs -f 容器名：仅对仍在运行的容器有效；若容器反复重启，可加
--restart=on-failure:1后立刻logs，避免日志被覆盖
注意：如果 docker logs 提示 “No such container”，说明容器根本没创建成功，要回看 docker run 命令终端输出，常见原因有镜像拉取失败、端口已被占、-v 挂载路径宿主机不存在等。
重点识别三类典型报错关键词
日志里出现这些，基本能锁定方向：
-
Permission denied：90% 是
runtime/、storage/或vendor/bin/hyperf.php权限问题。先ps aux | grep swoole看进程用户（常为www-data或镜像预设低权限用户），再ls -ld runtime storage vendor/bin/hyperf.php查属主，不匹配就chown -R www-data:www-data runtime storage，并chmod +x vendor/bin/hyperf.php -
Address already in use 或
port is already allocated：宿主机端口冲突。用lsof -i :9501（Hyperf 默认端口）查占用进程，或换 host 端口映射 -
failed to load config、invalid yaml、Connection refused：配置文件挂载错位、语法错误，或依赖服务（如 MySQL、Redis）未就绪。进容器手动检查：
docker run -it --rm --entrypoint /bin/sh 镜像名，然后ls -l /config、cat config/autoload/db.php、ping redis
进阶：绕过入口点手动调试
当日志太简略、看不出具体哪行代码崩了，就跳过默认启动逻辑，进镜像手动跑：
-
docker run -it --rm --entrypoint /bin/sh 镜像名（若无/bin/sh，试/bin/ash） - 进去后，切到项目目录，执行原启动命令：
php bin/hyperf.php start - 观察实时报错，同时可检查：
ls -l看目录权限、id看当前用户、php -m | grep swoole确认扩展已加载
