应直接选用 hyperf/hyperf 官方镜像并指定精确标签（如 8.1-alpine-v3.16-swoole），禁用 latest；因自行在 php:8.x-cli 上用 pecl 安装 Swoole 易导致 musl libc 不兼容、ABI 匹配失败、扩展缺失或编译选项遗漏等问题，且官方镜像默认不包含 pcntl，需多阶段构建添加。
直接选 hyperf/hyperf 官方镜像，但必须指定精确标签（如 8.1-alpine-v3.16-swoole），禁用 latest；不推荐基于通用 PHP 镜像自己装 Swoole，除非你明确需要定制扩展或调试底层行为。
为什么不能用 php:8.x-cli 自己装 Swoole？
Hyperf 依赖 Swoole ≥ 5.1.0，且需与 PHP 版本、libc、编译器 ABI 严格匹配。自己在 php:8.1-cli 上用 pecl install swoole 构建，容易踩这些坑：
- Alpine 镜像用 musl libc，而某些 C 扩展（如
redis或自定义协程驱动）未适配，运行时报undefined symbol: __libc_malloc - Swoole 编译时未启用
--enable-openssl或--enable-http2，导致 Hyperf 的 HTTPS/HTTP2 组件失效 - PHP 镜像内核版本过低（如 Debian bookworm 内核 io_uring 支持被静默降级，性能损失 20%+
- 每次构建都要重装 Swoole，破坏 Docker 层缓存，CI 构建时间多出 40–60 秒
hyperf/hyperf 镜像的标签怎么读？
官方镜像标签不是随意命名的，每个字段都对应关键约束：
-
8.1：Hyperf 主版本，对应 PSR-14 兼容性与核心组件 API -
alpine-v3.16：基础系统为 Alpine Linux v3.16（musl 1.2.4 + apk 2.14），体积约 6MB，适合无 glibc 依赖的服务 -
swoole：已预编译并启用 Swoole 扩展，版本固定为该标签对应的swoole-5.1.0（见 Docker Hub 镜像详情页的Labels字段）
错误示例：hyperf/hyperf:8.1-alpine（缺 swoole 后缀）——这个镜像不含 Swoole，启动直接报 Class 'Swoole\Http\Server' not found。
什么时候该放弃官方镜像，改用多阶段自建？
仅当满足以下任一条件时才值得折腾：
- 项目必须使用
php:8.3-rc等非 LTS PHP 版本，而官方hyperf/hyperf尚未发布对应标签（查 Docker Hub “Last pushed” 时间，若 >30 天未更新则视为停更） - 需要在镜像中预置企业私有 Composer 源（
composer config -g repo.packagist composer https://your.repo），且不允许运行时挂载配置 - 必须启用
pcntl+sockets+yaml等多个扩展，并验证其 ABI 兼容性（此时建议用debian:bookworm-slim基础层而非 Alpine）
注意：hyperf/hyperf 镜像默认不包含 pcntl，若你的命令行任务需 pcntl_fork，必须用多阶段构建自行添加，不能靠 docker-php-ext-enable pcntl 动态启用——该命令在官方镜像里会失败，因为编译时未保留 phpize 所需头文件。
最常被忽略的一点：Hyperf 官方镜像的 ENTRYPOINT 是空的，它只设了 WORKDIR /opt/www 和 USER www-data，所有启动逻辑仍由你自己的 CMD ["php", "bin/hyperf.php", "start"] 控制。别误以为拉下来就能跑，bin/hyperf.php 文件必须存在于 COPY 进去的代码里，且权限为可执行。
