应直接选用 hyperf/hyperf 官方镜像并指定精确标签(如 8.1-alpine-v3.16-swoole),禁用 latest;因标签各字段含义明确:8.1 对应 Hyperf 主版本,alpine-v3.16 表示基于 Alpine v3.16(musl libc 1.2.4),swoole 后缀表明已预装 Swoole-5.1.0;缺该后缀则无 Swoole 扩展,启动报错。

直接用 docker pull hyperf/hyperf:8.1-alpine-v3.16-swoole 这类带完整标签的镜像,别碰 latest 或缺 swoole 后缀的变体——它们要么版本模糊,要么根本没装 Swoole,一启动就报错。
选对标签是关键
Hyperf 官方镜像标签不是随便写的,每个字段都有明确含义:
- 8.1:对应 Hyperf 主版本,影响 PSR-14 兼容性与核心组件行为
- alpine-v3.16:基于 Alpine Linux v3.16(musl libc 1.2.4),体积小、启动快,适合无 glibc 依赖的服务
-
swoole:表示已预编译并启用 Swoole 扩展,版本固定为该标签对应的
swoole-5.1.0(可查 Docker Hub 的 Labels 字段确认)
错误示例:hyperf/hyperf:8.1-alpine —— 缺 swoole 后缀,镜像不含 Swoole 扩展,运行时直接抛 Class 'Swoole\Http\Server' not found。
国内拉取慢?换镜像加速源
默认走 Docker Hub 容易卡住,尤其在国内。推荐配置阿里云或网易镜像加速器:
Docker Hub (hub.docker.com)。此技能适用于所有 Docker Hub 操作,包括读取、创建、更新和删除数据。只要任务涉及 Docker Hub,就使用此技能。
- Windows/macOS:Docker Desktop 设置 → Docker Engine → 在
registry-mirrors数组里添加"https://xxx.mirror.aliyuncs.com"(替换为你的阿里云加速地址) - Linux:编辑
/etc/docker/daemon.json,加入镜像源配置后执行sudo systemctl restart docker
配置生效后,docker pull 会自动走代理,速度提升明显,避免超时中断。
验证镜像是否可用
拉完别急着跑,先检查基础能力:
- 运行容器并进入:
docker run -it --rm hyperf/hyperf:8.1-alpine-v3.16-swoole /bin/sh - 进容器后执行:
php -v看 PHP 版本,php --ri swoole确认 Swoole 已加载且版本 ≥ 5.1.0 - 退出后执行:
docker images | grep hyperf,确认镜像存在且大小合理(Alpine 版通常在 70–90MB 区间)
三项都通过,说明镜像拉取和基础环境没问题,可以继续下一步构建项目。










