Hyperf 在单机 PHP 环境下完全可用，关键需匹配协程引擎与运行时约束：Linux/macOS 原生支持 Swoole；Windows 必用 WSL2 或切换 Swow 驱动；PHP ≥ 8.1、Swoole ≥ 5.1（或 Swow ≥ 1.5）、禁用 opcache.enable_cli=1、启用协程，本地直连数据库填 127.0.0.1。
Hyperf 在单机 PHP 环境下完全可用，但需绕过常见误区——它不依赖 Docker 或 Linux 服务器才能跑起来，关键是匹配好底层协程引擎与运行时约束。
明确支持的本地环境组合
Hyperf 默认基于 Swoole，而 Swoole 官方仅支持 Linux/macOS 原生运行；Windows 用户必须通过 WSL2（非 Cygwin 或旧版 WSL1）启用完整 POSIX 支持。若坚持纯 Windows 原生环境，可切换 Swow 驱动：
- 安装 Swow 扩展（PHP 8.0+，需编译或使用预编译包）
- 修改
config/autoload/swoole.php中'driver' => 'swow' - Swow 兼容 Windows、macOS、Linux，且无需额外虚拟层
PHP 与扩展版本必须严格对齐
Hyperf 3.x 要求：
- PHP ≥ 8.1（Hyperf 3.2+ 已弃用 PHP 7.4/8.0）
- Swoole ≥ 5.1.0（若用 Swoole），或 Swow ≥ 1.5.0（若用 Swow）
- 禁用
opcache.enable_cli=1（CLI 模式下可能导致热重载异常） - 确保
swoole.enable_coroutine=1（Swoole 场景下必开）
本地启动与调试配置要点
- 使用
php bin/hyperf.php start启动服务，默认监听http://127.0.0.1:9501 - 开发阶段务必启用
hyperf/watcher：-
composer require hyperf/watcher --dev - 运行
php bin/hyperf.php vendor:publish hyperf/watcher生成.watcher.php - 监控目录建议设为
['app', 'config', 'routes']，避免扫描vendor或runtime
-
- 若遇到端口被占，修改
config/autoload/server.php中port字段即可，无需改系统防火墙
数据库与缓存本地直连配置
- MySQL/Redis 不必容器化：直接填写
127.0.0.1（非localhost，避免 Unix socket 解析歧义） -
.env中显式声明：DB_HOST=127.0.0.1 DB_PORT=3306 REDIS_HOST=127.0.0.1 REDIS_PORT=6379
- 如本地 Redis 启用密码，需在
config/autoload/cache.php中补全'auth' => env('REDIS_AUTH', '')
不复杂但容易忽略
立即学习“PHP免费学习笔记（深入）”；
