Hyperf在Linux启动失败多为静默退出，应先用php bin/hyperf.php start --verbose盯终端输出，查端口监听、PHP/Swoole版本及扩展，禁用opcache CLI，并手动打点日志定位卡点。
Hyperf在Linux系统中启动报错，往往不是“报错了”，而是“没报错却起不来”——进程静默退出、卡住不动、端口不监听，根本看不到堆栈。排查关键在于分层定位 + 优先验证最常见故障点，而不是一上来就翻代码。
看终端输出是否被吞掉
很多“无声失败”其实错误早打出来了，只是你没看到：
- 别用
php bin/hyperf.php start &后台启动，先直接运行php bin/hyperf.php start，盯住终端实时输出 - 加
--verbose参数：运行php bin/hyperf.php start --verbose，它会强制打印 DI 容器构建过程中的异常，90%的早期致命错误（如配置语法错、类找不到）靠它就能暴露 - 检查
stderr有没有被重定向：如果是 systemd 管理的服务，确认StandardError=journal已设置，并用journalctl -u your-service -n 50 -f实时跟踪
查端口和进程是否真在跑
报Address already in use或Connection refused，本质是端口没起来或被占了：
- 用
netstat -tulnp | grep :9501（或你实际配置的端口）看是否真有LISTEN状态；没有输出＝Swoole根本没启动成功 - 用
lsof -i :9501查谁在占端口；若显示多个 PHP 进程，优先对主进程（COMMAND列是php且无[worker]后缀的那个）发kill -USR2优雅终止 - 残留进程常藏在子进程里：执行
ps aux | grep hyperf再结合ps -o pid,ppid,comm -ef | grep php看是否有孤儿进程（PPID=1）
验环境与扩展是否就位
Hyperf 启动失败，80%卡在底层环境没达标：
- 确认 PHP 版本 ≥ 8.1：
php -v；低于则 Swoole 协程不可用，框架直接无法初始化 - 确认 Swoole 已启用协程：
php --ri swoole，输出中必须含support coroutines: enabled - 检查关键扩展是否存在：
php -m | grep -E "swoole|redis|mysqlnd|openssl"；缺任一都可能导致静默 fatal error - 临时禁用 opcache CLI 缓存：
php -d opcache.enable_cli=0 bin/hyperf.php start，避免旧字节码干扰
绕过日志组件，手动打点关键路径
日志系统本身依赖 DI 和配置，出问题时它自己都起不来。用原生方式快速验证执行流：
- 在
bin/hyperf.php第一行加：file_put_contents('/tmp/hyperf-start.log', date('Y-m-d H:i:s') . " bin loaded\n", FILE_APPEND); - 在
config/autoload/logger.php开头加：file_put_contents('/tmp/hyperf-start.log', date('Y-m-d H:i:s') . " logger config loaded\n", FILE_APPEND); - 启动后查
/tmp/hyperf-start.log，看执行停在哪一步，比猜快得多
