hyperf 启动失败主因是 swoole 扩展未正确安装或配置，需确保 php ≥ 8.1、extension=swoole 启用且 coroutine=enabled，并使用 php bin/hyperf.php server:watch 启用热更新。
Hyperf 不是“装完就能跑”的框架，它依赖 Swoole 协程引擎且必须常驻内存运行；跳过 Swoole 安装或忽略 PHP 版本限制，php bin/hyperf.php start 会直接报错退出，连欢迎页都看不到。
为什么 php bin/hyperf.php start 启动失败？
绝大多数启动失败都卡在 Swoole 扩展未就绪。Hyperf 不是 PHP-FPM 框架，它不走 web 服务器入口，而是靠 Swoole 启动一个独立协程 HTTP 服务器 —— 所以 extension=swoole 必须出现在生效的 php.ini 里，且 php --ri swoole 输出中必须含 coroutine => enabled。
- 用
php -i | grep "Loaded Configuration File"确认当前 CLI 模式加载的是哪个php.ini，别改错文件 - Ubuntu/Debian 下常见路径是
/etc/php/*/cli/php.ini，而 FPM 模式用的是另一份，二者不互通 -
pecl install swoole后若提示 “Please specify the installation prefix”，加-y参数：pecl install -y swoole - Alpine 镜像需先
apk add $PHPIZE_DEPS autoconf g++ make再装 Swoole，否则编译失败
Windows 用户别硬刚本地安装
Hyperf 官方明确不支持 Windows 原生运行（PHP 的 pcntl 和 posix 扩展在 Windows 下不可用），所谓“Windows 安装成功”基本是 Docker 容器内跑通了，宿主机只是个外壳。
- 别花时间折腾 WSL2 以外的方案，WSL2 是目前最接近 Linux 原生体验的方式
- Docker Desktop for Windows 必须开启 WSL2 backend，否则
hyperf/hyperf镜像启动后无法监听端口 - 挂载目录时路径要用 WSL2 路径格式，比如
-v /home/user/myapp:/hyperf-skeleton，而不是C:\myapp - 容器内执行
composer create-project时若报 “cannot run as root”，加--no-interaction --quiet跳过交互，或改用非 root 用户启动容器
composer create-project 卡住或报错
这不是 Hyperf 的问题，是 Composer 在国内访问 packagist.org 太慢或被限流导致的超时。官方 skeleton 模板本身没做特殊处理，所有依赖都走默认源。
- 执行前务必设置国内镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer - 如果已卡住，Ctrl+C 中断后清空缓存：
composer clear-cache，再重试 - Hyperf 3.x 要求 PHP ≥ 8.1，但很多教程仍用 7.4 镜像，
hyperf/hyperf:7.4-alpine-v3.11-swoole这类旧标签已不兼容新版本 skeleton - 创建项目时出现 “Package hyperf/hyperf-skeleton has a PHP requirement incompatible with your PHP version”，说明镜像 PHP 版本和 skeleton 要求不匹配，换
hyperf/hyperf:8.1-alpine或更高
修改代码后服务不自动重启
Hyperf 默认无热更新，每次改完 controller 或 config 都得手动 Ctrl+C + php bin/hyperf.php start，这是新手最常抱怨的点。官方 hyperf/watcher 组件能解决，但它不是开箱即用的。
- 先装依赖：
composer require hyperf/watcher --dev，注意--dev不能漏，否则生产环境也会带上 - 发布配置：
php bin/hyperf.php vendor:publish hyperf/watcher，这步生成config/autoload/watcher.php - 启动命令必须换成
php bin/hyperf.php server:watch，start命令此时已失效 - 默认只监听
app/和config/目录，加新目录如contract/需手动改watch.dir配置项
真正容易被忽略的是 Swoole 的 coroutine 支持状态和 watcher 的启动命令切换 —— 前者决定框架能不能跑，后者决定你愿不愿意继续写下去。别急着写业务逻辑，先让 curl http://127.0.0.1:9501 返回 {"message":"Welcome to Hyperf!"}，再碰代码。
