Hyperf 的 Docker 容器化部署需构建轻量镜像，含 Swoole 扩展（≥5.1.0）、多阶段构建优化、配置外挂及环境变量控制启停；通过 docker-compose 快速启动并验证服务。
Hyperf 的 Docker 容器化部署并不复杂，核心是构建一个轻量、可复用、符合 PSR-14 和 Swoole 运行要求的镜像，并通过 docker-compose 快速启动服务。关键在于 PHP 环境配置（含 Swoole 扩展）、应用代码复制时机、启动命令适配以及配置文件的外部化管理。
一、准备基础镜像（推荐 alpine + php:8.1-cli）
Hyperf 推荐使用 Alpine Linux 镜像以减小体积，同时需确保 Swoole 扩展已编译启用（v5.1+ 要求 Swoole ≥ 5.1.0）。官方不提供预装 Swoole 的 PHP 镜像，因此需自行构建：
- 基于
php:8.1-cli-alpine基础镜像 - 安装依赖：
apk add --no-cache $PHPIZE_DEPS autoconf g++ make - 用 pecl 安装 Swoole：
pecl install swoole，并启用扩展（docker-php-ext-enable swoole） - 可选：添加 pcntl、redis、yaml 等常用扩展支持
二、编写 Dockerfile（精简实用版）
避免在镜像中执行 composer install（会污染镜像层、影响缓存），推荐采用“多阶段构建”或“宿主机 composer install + COPY vendor”方式：
- 第一阶段：用完整 PHP 镜像运行
composer install --no-dev --optimize-autoloader - 第二阶段：仅 COPY
app/、config/、runtime/、vendor/和bin/hyperf.php - 设置工作目录为
/app，声明非 root 用户（如www-data）提升安全性 - 入口命令设为：
ENTRYPOINT ["php", "bin/hyperf.php", "start"]
三、配置 docker-compose.yml（支持开发与生产切换）
用环境变量控制启动模式（dev / prod），挂载配置与日志便于调试和持久化：
-
HYPERF_ENV=prod触发生产模式（禁用调试、启用 OPcache） - 挂载
./config:/app/config:ro实现配置热更新（注意权限） - 映射端口如
"9501:9501"，并暴露9502（WebSocket）或9503（HTTP2）按需开启 - 添加
restart: unless-stopped保障服务稳定性
四、启动与验证（三步到位）
完成构建后，快速确认服务是否正常运行：
- 执行
docker-compose build构建镜像 - 执行
docker-compose up -d后台启动容器 - 检查日志：
docker-compose logs -f hyperf；访问http://localhost:9501查看欢迎页或自定义健康接口 - 若报错 “Swoole extension not loaded”，说明镜像中 Swoole 未正确启用，需检查
docker-php-ext-enable步骤及php -m | grep swoole输出
整个流程无需修改 Hyperf 框架源码，所有定制通过配置和 Dockerfile 完成，适合 CI/CD 流水线集成。只要环境一致，本地构建的镜像可直接用于测试、预发、生产环境。
