必须使用 WSL2 或 Docker 部署 Hyperf，因 Swoole 不支持 Windows 原生环境；WSL2 需启用三项子系统功能并设为默认版本 2，推荐 Ubuntu 22.04；Docker 挂载路径须用正斜杠且同时指定 -v 和 -w；PHP 8.2 及 bcmath/sockets/xml 等扩展缺一不可；开发用 hyperf/watcher（scan_interval 设 2000ms），生产用 supervisord 或 restart=always。
在 Windows 上安装和部署 Hyperf，不能直接用原生 PHP 运行，必须借助兼容 Linux 环境的方案。核心难点在于 Swoole 扩展不支持 Windows 原生环境，官方明确要求使用 WSL2 或 Docker。下面按实际开发路径整理关键注意事项和操作要点。
必须启用 WSL2（非可选）
Hyperf 依赖 Swoole，而 Swoole 在 Windows 下无法以完整功能运行（缺少信号、进程控制等底层支持）。WSL2 是微软官方推荐、Hyperf 官方文档指定的 Windows 开发环境基础：
- 必须勾选「适用于 Linux 的 Windows 子系统」「虚拟机平台」「Windows 虚拟机监控程序平台」三项，缺一不可
- 安装后务必执行 wsl --status，确认显示 默认版本: 2；若为 1，需运行 wsl --set-version Ubuntu-22.04 2 升级
- Ubuntu 推荐使用 22.04 LTS（非 24.04），因部分 PHP 8.2 扩展在 24.04 中存在兼容性问题
Docker 部署更稳妥但需注意挂载规范
若倾向容器化，Docker Desktop 是首选，但 Windows 路径处理极易出错：
- 本地路径中的反斜杠 \ 必须全部改为正斜杠 /，例如 D:/project/my-hyperf，否则挂载失败
- -v 和 -w 必须同时指定：-v 挂载代码目录，-w 设置容器内工作目录，否则 php bin/hyperf.php start 会报找不到文件
- 镜像建议显式指定版本号（如 hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6），避免拉取 latest 导致 PHP/Swoole 版本不匹配
PHP 与扩展安装有严格顺序
在 WSL2 的 Ubuntu 中，不能跳过系统更新直接装 PHP，否则扩展编译会失败：
- 先执行 sudo apt update && sudo apt upgrade -y，确保系统基础库最新
- PHP 8.2 是当前 Hyperf 3.x 最稳定版本，安装命令中 php8.2-cli 和 php8.2-dev 缺一不可（后者是编译 Swoole/Redis 所需）
- 必须额外安装 php8.2-bcmath php8.2-sockets php8.2-xml，Hyperf 核心组件（如 JSON-RPC、协程 HTTP 客户端）强依赖这些扩展
热重载与自启动需分场景配置
Hyperf 自身不提供 Windows 服务注册能力，开发与生产启动方式不同：
- 开发阶段用 hyperf/watcher：安装后生成 .watcher.php，注意 scan_interval 建议设为 2000ms（太小加重 CPU，太大延迟感知）
- 生产环境不能依赖 watcher，应使用 supervisord（WSL2）或 docker restart=always（Docker）实现进程守护
- 切勿在 Windows 命令行直接运行 php bin/hyperf.php start，即使装了 WAMP/XAMPP 也会因缺少 Swoole 而报错
