hyperf 在 windows 上无法直接运行，因其核心依赖 swoole 扩展官方不支持 windows 原生环境，强行执行 php bin/hyperf.php start 会报错 “the ext-swoole is required”；唯一稳定方案是使用 docker 容器运行，需正确配置 -w 工作目录、完整启动命令 php bin/hyperf.php start、正斜杠路径、显式端口映射 -p 9501:9501，并注意镜像 php 版本匹配及 .env 文件仅启动时加载。
Hyperf 在 Windows 上不能直接运行，因为它的核心依赖 swoole 扩展官方不支持 Windows 原生环境。强行执行 php bin/hyperf.php start 会报错：The ext-swoole is required。唯一稳定、可复现的方案是用 Docker 容器运行。
为什么不能在 Windows 命令行直接启动 Hyperf
Windows 缺少 swoole 的编译环境和运行时支持，即使你装了 WSL2，也只影响 Linux 子系统——而你在 PowerShell 或 CMD 里执行的 PHP 进程仍是 Windows 原生进程，无法加载 swoole。这不是配置问题，是扩展层面的硬性限制。
-
swoole的 Windows 支持仅限于实验性分支（如swoole-win），但 Hyperf 官方明确不兼容该分支 - PHP-FPM 模式无法替代：Hyperf 的协程能力、服务注册发现、热重载等特性都强依赖
swoole的事件循环 - 某些教程提到“用 WSL2 装 PHP + Swoole”，那是在 WSL2 里跑整个开发环境，不是“Windows 环境下运行”，属于换平台而非适配
docker run 命令必须带 -w 和完整启动命令
很多人挂载了代码目录却容器秒退，根本原因是没指定工作目录或漏写启动命令。Docker 镜像默认没有入口点（ENTRYPOINT），不显式告诉它“去哪、做什么”，它就执行完 shell 就退出。
-
-w /var/www/html或-w /data/project必须与-v挂载路径终点一致，否则bin/hyperf.php找不到 - 启动命令必须写全：
php bin/hyperf.php start，不能只写php或bin/hyperf.php - 镜像标签要匹配 PHP 版本，例如
hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6中的8.2对应 PHP 8.2，别混用7.4镜像跑 PHP 8.2 项目
端口映射和路径分隔符容易出错
Windows 用户常在 -v 参数里用反斜杠 \ 或混合路径格式，导致挂载失败——Docker Desktop for Windows 要求使用正斜杠 /，且盘符后跟冒号不能有空格。
- 正确：
-v E:/my-hyperf-app:/var/www/html - 错误：
-v E:\my-hyperf-app:/var/www/html（反斜杠） - 错误：
-v E:/my-hyperf-app :/var/www/html（冒号前有空格） - 端口映射必须显式写
-p 9501:9501，只写-P会随机分配主机端口，你没法固定访问localhost:9501
改代码后要手动重启，热重载需额外装 hyperf/watcher
Hyperf 默认不监听文件变化。挂载目录后改本地代码，容器内进程不会自动重启——这是设计使然，不是 bug。
- 临时方案：进容器按
Ctrl+C终止，再执行一次php bin/hyperf.php start - 长期开发建议装热重载：
composer require hyperf/watcher，然后运行php bin/hyperf.php vendor:publish hyperf/watcher生成.watcher.php -
.watcher.php中的scan_interval建议设为2000（2 秒），太小会增加 CPU 负载；dir列表只加app和config，别加vendor或runtime
真正麻烦的不是启动命令本身，而是每次改完 .env 或配置后，得确认容器内是否读到了新值——因为 .env 是启动时加载的，不是运行时动态重读的。这点很容易被忽略，尤其当你以为改了就生效，结果接口一直连不上 Redis 或 MySQL。
