Hyperf 启动失败主因是 PHP 环境、Swoole 加载与配置生效三关未过：需 PHP ≥ 8.0、Swoole 扩展启用且关键功能（async_redis/openssl）开启、disable_functions 不禁用 pcntl_fork 等；必须用 create-project 初始化项目；.env 和 dev.php 需调为开发模式并开放监听地址；排查应先验证 Swoole 是否加载，再重建 autoload。
Hyperf 不是装完就能跑的框架，composer create-project 只是起点，真正卡住人的永远是 PHP 环境、Swoole 加载和配置生效这三关。
PHP 和 Swoole 扩展必须同时满足硬性要求
Hyperf 3.x 要求 PHP ≥ 8.0，且 swoole 必须已加载并启用关键能力。仅版本达标但扩展未启用，启动时会直接报 Class 'Swoole\Http\Server' not found。
- 运行
php -v确认输出为PHP 8.0.0或更高（7.4已彻底不支持） - 运行
php -m | grep swoole，有输出才说明扩展已注册；若无，需检查php.ini是否漏加extension=swoole.so - 运行
php --ri swoole，重点看support async_redis => enabled、openssl => enabled这两项是否为enabled，否则后续 Redis 或 HTTPS 请求会失败 -
disable_functions若包含pcntl_fork、exec、shell_exec，Hyperf 启动时无法 fork worker 进程，会静默退出
用 create-project 而不是 require
在现有项目里 composer require hyperf/hyperf 几乎必然失败——Hyperf 依赖预设的目录结构、bin/hyperf.php 入口、以及严格对齐的 psr-4 自动加载映射。手动引入只会触发 Class not found 或容器初始化失败。
- 必须用
composer create-project hyperf/hyperf-skeleton project-name ^3.1初始化全新项目（^3.1锁定稳定主线，避免dev-main的协程行为变更） - 国内安装慢？先执行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（PHP Composer 官方镜像已停用） - 若提示
Your requirements could not be resolved，大概率是 PHP 版本或 Swoole 版本不匹配，不是 Composer 本身问题
.env 和 dev.php 必须改，否则连 500 错误都看不到
新项目默认配置下，开发时几乎无法调试：错误被静默吞掉、监听地址绑定到 127.0.0.1 导致容器外访问失败、调试开关关闭导致空白响应。
- 修改
.env：APP_ENV=dev、SWOOLE_HTTP_HOST=0.0.0.0（不是127.0.0.1）、SWOOLE_HTTP_PORT=9501 - 修改
config/autoload/dev.php中的'debug' => false为true，否则任何异常只返回空响应 - Docker 场景下，还需确认
docker run -p 9501:9501映射正确，且容器内能读取/proc/sys/net/core/somaxconn（Swoole 启动校验项）
启动失败时，先别急着查代码逻辑
90% 的启动失败发生在环境层，而不是业务代码。最有效的排查路径是绕过框架，直击底层依赖。
- 执行
php bin/hyperf.php start前，先运行php -r "var_dump(extension_loaded('swoole'));"，确保输出bool(true) - 删掉
vendor/autoload.php和vendor/composer/autoload_*.php，再执行composer dump-autoload -o重建自动加载 - Windows 用户不要直接运行
bin/hyperf.php start，必须用php bin/hyperf.php start（#!/usr/bin/env php在 CMD 下无效） - 如果
php bin/hyperf.php start报错但没堆栈，说明dev.php的debug没开，或者APP_ENV仍是prod
Hyperf 的“高性能”建立在 Swoole 持久化进程之上，而这个进程能否起来，完全取决于 PHP CLI 环境是否干净、扩展是否真就位、配置是否真生效——这些细节不显眼，但错一个，整个服务就卡在启动前。
