Hyperf 3.1 生产部署必须容器化：需确保项目根目录含 composer.json、config/、runtime/、.env、Dockerfile 五要素，runtime/不可被 .dockerignore 删除；推荐多阶段 Dockerfile 构建轻量镜像，并通过 curl http://localhost:9501/health 验证服务就绪。
Hyperf 3.1 项目要上线生产环境，必须通过 Docker 容器化部署，否则无法接入 Kubernetes 编排体系，也无法满足 CI/CD 流水线对镜像制品的强制要求。
确认 Hyperf 3.1 项目结构是否适配容器化
进入项目根目录，检查是否存在 【composer.json、config/、runtime/、.env、Dockerfile】这 5 个关键文件或目录；缺任一者都可能导致构建失败或运行时配置丢失。特别注意 runtime/ 目录不能被 .dockerignore 误删——它用于存放协程上下文、日志和缓存，容器启动后首次写入会自动创建，但若构建阶段被剔除，会导致服务启动卡在 “Loading config” 环节。
执行 php bin/hyperf.php start 在本地验证服务可正常启动，确保 no error log 输出且 HTTP 端口（默认 9501）能响应 curl 请求；这一步跳过将导致后续镜像运行后直接 exit 1。
编写符合云原生规范的 Dockerfile
方法一：基础精简版（推荐用于开发测试）
FROM php:8.1-cli-alpine
RUN apk add --no-cache tzdata && cp -rf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --ignore-platform-reqs
COPY . .
EXPOSE 9501
CMD ["php", "bin/hyperf.php", "start"]
方法二：生产强化版（必须启用多阶段构建）
① 构建阶段：
FROM php:8.1-cli-alpine AS builder
RUN apk add --no-cache $PHPIZE_DEPS autoconf automake autoheader libtool
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --ignore-platform-reqs
COPY . .
RUN php bin/hyperf.php gen:proxy && php bin/hyperf.php gen:amqp && php bin/hyperf.php gen:command
② 运行阶段：
FROM php:8.1-cli-alpine
RUN apk add --no-cache tzdata && cp -rf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
WORKDIR /app
COPY --from=builder --chown=www-data:www-data /app /app
USER www-data
EXPOSE 9501
CMD ["php", "bin/hyperf.php", "start"]
【务必删除 vendor/.git 和 tests/ 目录再 COPY，否则镜像体积暴涨 300MB+】 多阶段构建中若未显式清理 dev 依赖（如 phpunit、mockery），会导致最终镜像残留大量无用文件，违反云原生“最小镜像”原则。
构建并验证镜像
执行 docker build -t hyperf31-prod:20260806 . 启动构建；注意末尾的 . 不可省略，表示构建上下文为当前目录。
构建成功后，运行 docker run -d --name hyperf-test -p 9501:9501 hyperf31-prod:20260806 启动容器。
立即执行 curl http://localhost:9501/health 验证服务响应；若返回 JSON {“status”:“ok”}，说明容器内服务已就绪；若超时或 connection refused，先 docker logs hyperf-test 查看错误，大概率是 config/autoload/server.php 中 port 被硬编码为 0.0.0.0:9501 导致绑定失败——容器内应只监听 9501，不带 IP 前缀。
最后执行 docker exec -it hyperf-test ls -l runtime/container，确认 Diactoros 实例与 AOP 代理类已生成；缺失则说明 gen:proxy 步骤未生效，需回查 Dockerfile 中 RUN 命令是否遗漏或顺序错误。
