Windows 本地无法直接运行 Hyperf 多进程定时任务，因其依赖 Linux/macOS 的 pcntl 和 fork 机制；推荐方案为 WSL2 + Ubuntu 22.04 或 Docker 容器化运行，二者均能完整支持 Crontab 组件及协程调度。
Windows 本地直接运行 Hyperf 的多进程定时任务（如 Crontab）不可行，因为 Hyperf 的 Crontab 组件依赖 Linux/macOS 的进程模型与信号机制，Windows 原生不支持 pcntl 扩展，也无法可靠 fork 子进程。必须通过兼容层或容器化方式实现。
推荐方案：WSL2 + Ubuntu 22.04 运行定时任务
这是目前最稳定、最贴近生产环境的本地开发方式，能完整支持 Hyperf 的 Crontab、Process 和协程调度能力。
- 确保 WSL2 已启用并设为默认版本：
wsl --set-default-version 2；若失败，先安装官方内核更新包（wsl2kernel.exe） - 安装 Ubuntu 22.04 LTS（非 24.04），避免 glibc 版本冲突导致 Swoole 协程失效
- 在 WSL2 中安装 PHP 8.2 及必需扩展：
php8.2-cli、php8.2-dev、php8.2-bcmath、php8.2-xml、php8.2-sockets - 用
pecl install swoole编译安装 Swoole ≥ 5.1，并确认php --ri swoole输出含support coroutines: enabled - 项目中启用定时任务：在
config/autoload/crontab.php中注册类，且确保enable_coroutine => true，所有 I/O 操作使用协程安全组件（如Hyperf\DbConnection）
Docker 容器内运行（无需 WSL2）
适合不想配置 WSL 或需快速验证的场景，但需注意权限与挂载细节。
- 拉取兼容镜像：
docker pull hyperf/hyperf:8.2-alpine-v3.19-swoole（Alpine 稳定性优于 Ubuntu 镜像） - 启动容器时必须加
--privileged和-u root，否则pcntl_fork调用失败，Crontab 进程无法创建 - 挂载项目目录并映射端口：
docker run -d --name hyperf-cron -v D:\myapp:/data/project -p 9501:9501 --privileged -u root -it hyperf/hyperf:8.2-alpine-v3.19-swoole - 进入容器后执行：
cd /data/project && php bin/hyperf.php start，框架会自动加载并运行Crontab进程 - 日志查看：
docker logs -f hyperf-cron，确认输出类似[INFO] Start crontab worker #1
绕过 Windows 限制的轻量替代方案
若仅需秒级/分钟级触发、不依赖进程隔离，可用事件驱动+协程 sleep 模拟，但不适用于长周期或高精度任务。
- 在
Command类中写一个常驻命令：php bin/hyperf.php my:cron - 内部用
while (true) { ... Coroutine::sleep(60); }循环检查时间，调用业务逻辑 - 配合
supervisor（WSL2 内）或 Windows 任务计划程序（外部触发脚本）维持常驻 - 注意：此方式无进程管理、无错误隔离，仅作临时调试或低频任务，不可替代正式 Crontab
关键避坑点
无论哪种方式，以下配置缺失都会导致定时任务静默失败：
-
config/autoload/server.php中'enable_coroutine' => true必须显式设置 -
bin/hyperf.php开头必须有Swoole\Runtime::enableCoroutine(true) - 数据库/Redis 连接必须使用 Hyperf 封装的协程客户端，原生 PDO 或 phpredis 会阻塞整个事件循环
- 路径必须用
BASE_PATH或DIRECTORY_SEPARATOR构建，避免 Windows 下反斜杠导致配置加载失败
