在 Windows 上使用 Docker Desktop 快速运行 Hyperf 框架（完整避坑指南） (但是使用GUI图形界面的时候我的 hyperf项目运行马上退出了,还在排查)
环境：Windows 10/11 + Docker Desktop + PowerShell + Hyperf 3.x
镜像：hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6

🎯 前言

Hyperf 是一个高性能、高灵活性的 PHP 协程框架，基于 Swoole 扩展构建。但由于 Swoole 官方不支持 Windows 直接运行，很多新手在本地开发时会遇到 The ext-swoole is required 等错误。

✅ 正确姿势是：使用 Docker 容器运行 Hyperf！

本文将手把手教你如何在 Windows + Docker Desktop 环境下，成功启动并访问你的 Hyperf 项目，全程避坑！

🔧 准备工作

1. 已安装 Docker Desktop for Windows
2. 已安装 Composer
3. 本地有一个 Hyperf 项目（路径示例）：
   E:phpStudy_64phpstudy_proWWWmy-hyperf-app

💡 如果还没有项目，先创建：
cd E:phpStudy_64phpstudy_proWWW
composer create-project hyperf/hyperf-skeleton my-hyperf-app
❌ 常见错误（你可能踩过的坑）

• 直接在 Windows 用 php bin/hyperf.php start → 报错：The ext-swoole is required
• 使用 Docker 但没挂载目录 → 修改代码无效
• 容器启动后秒退 → 没有指定正确的启动命令
• 访问不了 localhost:9501 → 端口未映射

✅ 正确运行步骤（PowerShell 命令行方式）

第一步：删除旧容器（可选）

docker rm -f my-hyperf-app

第二步：运行容器（关键命令）

docker run -d
–name my-hyperf-app
-p 9501:9501
-v E:/phpStudy_64/phpstudy_pro/WWW/my-hyperf-app:/var/www/html
-w /var/www/html
hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6
php bin/hyperf.php start

docker rm -f my-hyperf-app; docker run -d --name my-hyperf-app -p 9501:9501 -v E:/phpStudy_64/phpstudy_pro/WWW/my-hyperf-app:/var/www/html -w /var/www/html hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6 php bin/hyperf.php start

🔔 重点说明：

• -v：将本地项目挂载到容器 /var/www/html
• -w：设置工作目录（必须！否则找不到 bin/hyperf.php）
• php bin/hyperf.php start：启动命令（不是 php80！）
• 路径中的 必须改为 /（Docker on Windows 要求）

🔍 验证是否成功

1. 查看容器状态
   docker ps

✅ 应看到 my-hyperf-app 处于 Up 状态。

2. 查看日志
   docker logs my-hyperf-app

✅ 成功输出：
Server started at http://0.0.0.0:9501

3. 访问服务
   打开浏览器访问：
   http://localhost:9501

如果返回 JSON（如 {“message”:“Hello Hyperf.”}），恭喜你，成功了！

⚠️ 常见问题排查
问题 原因 解决方案
exec: “php80”: not found 用了本地别名 php80 改为 php

容器秒退 缺少启动命令或工作目录 确保 -w 和 php bin/hyperf.php start

挂载失败 路径格式错误 用 E:/… 而不是 E:…

端口不通 未映射端口 加 -p 9501:9501

📦 推荐：使用 docker-compose.yml（更优雅）

在项目根目录创建 docker-compose.yml：

version: ‘3’
services:
hyperf:
image: hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6
container_name: my-hyperf-app
ports:
- “9501:9501”
volumes:
- ./my-hyperf-app:/var/www/html
working_dir: /var/www/html
command: php bin/hyperf.php start
restart: unless-stopped

启动：
docker-compose up -d

停止：
docker-compose down

✅ 总结

• 不要在 Windows 本地直接运行 Hyperf，必须用 Docker
• 挂载目录 + 端口映射 + 启动命令 是三大核心要素
• 永远用 php，不要用 php80
• 使用 docker logs 查看日志是调试的关键

通过本文的方法，你可以轻松在 Windows 上开发和调试 Hyperf 应用，享受协程带来的高性能体验！

🔗 参考资料

• Hyperf 官方文档
• Docker Desktop for Windows

原创不易，转载请注明出处！
如果你觉得本文对你有帮助，欢迎点赞、收藏、关注～ 😊