用hyperf官方镜像可5分钟快速搭建服务：拉取预装php8.1+、swoole≥5.1的alpine镜像，挂载代码目录运行容器，执行composer create-project和require hyperf/http-server，编写autocontroller注解控制器，访问/api/index即得json响应。
用 Hyperf 官方镜像在 Linux 上快速搭建服务，核心是跳过本地环境配置，直接复用预装好 PHP 8.1+、Swoole ≥5.1、Composer 等依赖的容器镜像。整个过程不编译扩展、不调版本冲突，5 分钟内可跑通一个带路由的 API 服务。
拉取并运行官方镜像
Hyperf 官方维护了多版本 Alpine 镜像（如 hyperf/hyperf:8.0-alpine-v3.16-swoole），已内置 Swoole 扩展和常用 CLI 工具。执行以下命令即可启动一个交互式开发容器：
- 运行容器并挂载宿主机代码目录：
docker run -it --name hyperf-dev -v $(pwd):/app -p 9501:9501 -w /app hyperf/hyperf:8.0-alpine-v3.16-swoole /bin/sh - 进入容器后，直接创建骨架项目：
composer create-project hyperf/hyperf-skeleton . - 安装 HTTP 服务器组件（必需）：
composer require hyperf/http-server
编写控制器并验证路由
在挂载目录中新建 app/Controller/IndexController.php：
- 内容需含
#[AutoController(prefix: '/api')]注解，注意 prefix 以/开头、不以/结尾； - 方法返回数组，自动转 JSON；
- 保存后，在容器内执行：
php bin/hyperf.php start； - 宿主机访问
http://127.0.0.1:9501/api/index，应返回{"status":"ok","timestamp":...}。
持久化启动与简单反向代理
避免每次手动进容器启动，可用 docker-compose.yml 管理：
- 定义服务，指定工作目录、端口、挂载路径和启动命令：
command: php bin/hyperf.php start； - 若需域名或 HTTPS，用 Nginx 做反向代理，把
location /转发到http://127.0.0.1:9501； - WebSocket 支持需额外加
proxy_set_header Upgrade websocket等头； - 配置生效后，
docker-compose up -d即可后台常驻运行。
常见问题直击
实际操作中最容易卡在这几个点：
- 镜像拉不下来？换国内镜像源：
docker pull registry.cn-hangzhou.aliyuncs.com/hyperf/hyperf:8.0-alpine-v3.16-swoole； - 访问超时？检查是否漏装
hyperf/http-server，骨架默认不含该组件； - 路由 404？确认控制器文件名是
IndexController.php（大小写敏感），且类名与文件名一致； - 容器启动就退出？可能是
php bin/hyperf.php start启动后前台阻塞，确保没加&或后台化逻辑干扰。
