在 Windows 上使用 Docker Desktop 快速运行 Hyperf 框架

在 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 项目，全程避坑！

🔧 准备工作

已安装 Docker Desktop for Windows
已安装 Composer
本地有一个 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

bash 复制代码

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 要求）

🔍 验证是否成功

查看容器状态
docker ps

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

查看日志
docker logs my-hyperf-app

✅ 成功输出：

Server started at http://0.0.0.0:9501

访问服务
打开浏览器访问：
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

原创不易，转载请注明出处！

如果你觉得本文对你有帮助，欢迎点赞、收藏、关注～ 😊