Hyperf 在 Windows 上需通过 WSL2 运行，macOS 推荐本地部署并禁用 Spotlight 索引，Linux 应显式指定 FswatchDriver 并调优 inotify；跨平台统一靠环境变量驱动配置与路径规范。
Hyperf 原生不支持 Windows 直接运行，核心限制来自 Swoole 引擎——它仅兼容 Linux 和 macOS。但跨平台开发需求真实存在，关键不是“能不能用”，而是“怎么用得稳、改得少、启动快”。下面从实际可操作角度说明适配方案。
Windows 开发：优先选 WSL2，慎用 Docker for Windows
WSL2（Windows Subsystem for Linux 2）是目前 Windows 下最接近原生体验的方案：
- 安装 Ubuntu 22.04 或 24.04 发行版，直接在终端中安装 PHP 8.1+、Swoole 5.0+ 和 Composer
- 项目代码放在 WSL 文件系统内（如 /home/user/my-hyperf），避免挂载 Windows 路径，防止文件监听失效或性能骤降
- FswatchDriver 在 WSL2 中可正常工作，但需关闭默认缓冲：在 config/autoload/watcher.php 中设置 'latency' => 0.01（单位秒），降低事件延迟至 10ms 级别
- 不推荐 Docker for Windows：家庭版兼容性差，Docker Desktop 的文件共享机制会导致 runtime/ 目录写入缓慢、ScanFileDriver 扫描卡顿，甚至热重载失效
macOS 开发：本地部署更优，但需绕过 Docker 共享瓶颈
Mac 用户若用 Docker，会因 osxfs 文件系统桥接导致 Hyperf 启动慢、watcher 响应迟钝；本地部署更合适：
- 用 Homebrew 安装 PHP 8.1+（brew install php）、Swoole（pecl install swoole），并确认 pcntl、posix 已启用
- 禁用 Spotlight 索引项目目录：mdutil -i off /path/to/hyperf-project，减少文件系统干扰
- 若仍用 Docker，改用 docker run -v $(pwd):/app:cached（加 :cached 标志），缓解挂载延迟
- FswatchDriver 在 macOS 上默认使用 fsevents，比轮询高效，但需确保 .env 中未误设 WATCHER_DRIVER=scan
Linux 生产与开发：配置精简 + 驱动显式指定
Linux 环境最稳定，但不同发行版默认行为有差异，需统一收口：
- 统一使用 FswatchDriver，而非 ScanFileDriver：在 watcher.php 中明确写死 'driver' => FswatchDriver::class，避免因扩展缺失自动降级
- 在 CentOS/RHEL 系统上，确保已安装 inotify-tools（yum install inotify-tools），否则 fswatch 可能静默失败
- 调整内核参数防监听句柄耗尽：echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
- PHP-FPM 模式下无法使用协程 watcher，务必确认运行的是 php bin/hyperf.php start，而非通过 Nginx + PHP-FPM 启动
跨平台统一配置技巧
让同一套代码在三端都可靠运行，靠的是配置隔离与环境感知：
- 用 env 变量区分驱动：在 .env 中设 WATCHER_DRIVER=fswatch，代码里读取后实例化对应类，避免硬编码
- 监听路径避开跨平台敏感目录：不要监听 vendor 或 node_modules，它们在不同系统下符号链接处理不一致
- 所有路径拼接用 dirname(__DIR__) 或 BASE_PATH 常量，不用 __DIR__.'/../app' 这类易出错写法
- CI/CD 流水线中，Linux 构建机跑测试，Windows/macOS 仅做代码检查和打包，不执行 start 命令
