Hyperf在WSL2下启动失败主因是环境未对齐：WSL2内核未更新（需wsl --update或手动安装）、PHP CLI未启用Swoole协程（swoole.enable_coroutine=On且opcache.enable_cli=Off）、网络配置错误（MySQL/Redis须用127.0.0.1而非localhost）。
Hyperf 在 WSL2 下能跑通，但卡在某个环节就起不来——大概率不是 Hyperf 本身的问题，而是 WSL2 环境没对齐底层约束。Windows 原生 PHP 不支持 Swoole 协程，必须走 WSL2，且版本、扩展、配置三者缺一不可。
WSL2 系统与内核必须到位
很多失败从第一步就开始了：WSL2 没真正启用或内核缺失。不要只看 wsl -l -v 显示 version 2 就以为 OK。
- 管理员 PowerShell 执行
wsl --status，确认输出里有Default Version: 2 - 执行
wsl --update强制更新内核（2026 年多数用户仍卡在旧版） - 若报错
0x800701bc，必须手动下载并安装 WSL2 Linux kernel update package - Ubuntu 推荐用
Ubuntu-24.04（非 20.04），避免php8.2编译时libxml2版本不兼容
PHP + Swoole 版本必须严格匹配
Hyperf 3.2 要求 PHP ≥ 8.1、Swoole ≥ 5.1.0，但光装对版本还不够——CLI 模式下 Swoole 必须启用协程，且不能被 OPcache 干扰。
- 在 WSL2 中运行
php -v和php --ri swoole，确认swoole.enable_coroutine => On - 检查
opcache.enable_cli是否为Off（php --ini找到 cli.ini，加一行opcache.enable_cli=0） - 禁用
swoole.use_shortname：在php.ini加swoole.use_shortname=Off - 验证扩展加载：
php -r "var_dump(extension_loaded('swoole'));"必须返回bool(true)
Hyperf 启动前的三个硬性检查点
项目能 composer install 成功 ≠ 能 start 成功。本地启动失败八成卡在这三处。
-
php bin/hyperf.php start报Class 'Swoole\Http\Server' not found？说明 Swoole 扩展未启用或 PHP CLI 用了另一个 ini 文件 - 访问
http://127.0.0.1:9501连不上？先curl -v http://127.0.0.1:9501看是否返回 HTTP 200，再检查 WSL2 的netstat -tuln | grep 9501是否监听0.0.0.0:9501（不是127.0.0.1） - VSCode 调试进不去断点？确保 launch.json 中
"runtimeExecutable"指向 WSL2 里的 php（如/usr/bin/php），不是 Windows 本机路径
数据库和热重载别漏掉关键配置
本地开发最常忽略的两个细节：直连地址写错、watcher 配置没生效。
- MySQL/Redis 连接填
127.0.0.1，**不能写localhost**（WSL2 下 localhost 指向自身，不是宿主 Windows） - 装
hyperf/watcher后必须运行php bin/hyperf.php vendor:publish hyperf/watcher，否则.watcher.php不会生成 - 默认 watcher 只监控
app/和config/，改了bin/或runtime/下的文件不会重启——需要手动加进watch.dir
WSL2 里 Hyperf 最脆弱的环节不在代码，而在 PHP CLI 的 ini 加载顺序、Swoole 的协程开关状态、以及网络层对 127.0.0.1 的实际指向——这些地方出问题，错误信息往往不报具体原因，只能靠逐项排除。
