Swoole扩展未加载导致Hyperf启动失败：需确认容器内是否真实启用swoole，检查镜像标签是否含-swoole后缀、php -m | grep swoole输出、php --ri swoole状态及extension=swoole.so配置是否生效。
Hyperf 项目在 Docker 中启动失败，如果报错指向 Swoole 相关（比如 Class 'Swoole\Http\Server' not found 或 Extension 'swoole' is not loaded），那基本可以确定是 Swoole 扩展没启用或加载失败——这不是配置问题，是环境缺失。
确认容器内是否真的加载了 swoole 扩展
别只看 php -v 或 phpinfo() 页面，得进容器里查真实状态：
- 用
docker exec -it <hyperf-container-name> sh进入容器 - 运行
php -m | grep swoole—— 如果没输出，说明扩展根本没加载 - 再运行
php --ri swoole—— 如果报Extension 'swoole' does not exist，就是未安装或编译失败 - 检查扩展文件是否存在：
ls /usr/lib/php/extensions/*/swoole.so（路径依基础镜像而异）
hyperf/hyperf 镜像中 swoole 的启用逻辑
官方 hyperf/hyperf 镜像（如 8.1-alpine-v4.8-swoole）默认已预装 Swoole，但有三个关键前提：
- 必须使用带
swoole后缀的镜像标签，例如hyperf/hyperf:8.1-alpine-v4.8-swoole；hyperf/hyperf:8.1-alpine这类纯 PHP 镜像不含 Swoole - 镜像构建时需启用
--enable-swoole编译参数，且依赖libswoole和php-swoole包（Alpine 下是php81-swoole） - PHP 配置中必须有
extension=swoole.so，且该.so文件路径与extension_dir一致
常见踩坑点：Dockerfile 里手动装 swoole 却漏了关键步骤
如果你自己写 Dockerfile 基于 php:alpine 构建，很容易掉进这些坑：
- 只运行
pecl install swoole，但没加docker-php-ext-enable swoole—— 这步才是写入php.ini的关键 - Alpine 下用
apk add php81-swoole，但没确认 PHP 主版本号是否匹配（比如用了php82-swoole却跑在php81环境下） - 修改了
php.ini路径，但docker-php-ext-enable默认只改/usr/local/etc/php/conf.d/docker-php-ext-swoole.ini，若你删了这个目录或覆盖了conf.d，扩展就失效 - 使用
hyperf-skeleton模板时，composer install阶段若跳过--ignore-platform-reqs，可能因 Swoole 版本不满足hyperf/framework要求而静默失败
快速验证和修复建议
最省事的办法是直接换镜像：
- 把
docker-compose.yml中hyperf服务的image改成明确带swoole的官方镜像，例如：hyperf/hyperf:8.1-alpine-v4.8-swoole - 删掉自定义的
pecl install或apk addswoole 步骤，避免冲突 - 启动后立刻执行：
docker-compose exec hyperf php --ri swoole | grep "Version\|enabled"，确认输出含enabled和有效版本号 - 如果仍失败，检查
entrypoint是否覆盖了默认启动命令，导致 Swoole 初始化时机被破坏（比如硬编码php -S就绕过了 Swoole Server）
真正麻烦的不是装不上，而是装上了但没生效——比如 php.ini 加载顺序错乱、多个 extension= 行互相覆盖、或者 Alpine 镜像里 swoole.so 依赖的 libstdc++ 缺失却无提示。这类问题不会报错，只会让 start 命令卡住或秒退，必须进容器一层层验。
