先查 wsl --status 和内核更新包，若无“Default Version: 2”或提示未启用，需勾选“适用于 Linux 的 Windows 子系统”“虚拟机平台”“Windows 虚拟机监控程序平台”并重启，再手动安装 wsl2kernel.exe，最后执行 wsl --set-default-version 2。
WSL2 启用失败时先查 wsl --status 和内核更新包
很多人在执行 wsl --install 后仍报错 Error: 0x800701bc，本质是 WSL2 内核没装。别急着重装系统或换发行版，先在管理员 PowerShell 中运行：
wsl --status
若输出里没有「Default Version: 2」，或提示「The Windows Subsystem for Linux is not enabled」，说明基础功能未开启。此时应分两步处理：
- 确认「适用于 Linux 的 Windows 子系统」「虚拟机平台」「Windows 虚拟机监控程序平台」三项已在「Windows 功能」中勾选并重启
- 手动下载微软官方
wsl2kernel.exe（地址：https://www.php.cn/link/374d383550f673cead5c903caca73d6f），安装后再次执行wsl --set-default-version 2
跳过内核安装直接拉 Ubuntu 镜像，后续 Docker Desktop 启动会卡死或报「wsl2 backend not ready」——这是最常被忽略的前置硬门槛。
Ubuntu 发行版选 22.04 LTS 而非 24.04，避免 hyperf/hyperf:8.1 兼容问题
虽然 wsl --install -d Ubuntu-24.04 看起来新，但 Hyperf 官方镜像目前（截至 2026 年 8 月）主流仍基于 Alpine 3.11/3.12 或 Ubuntu 22.04 构建。24.04 默认使用 glibc 2.39+，而 hyperf/hyperf:8.1-alpine-v3.12-swoole 依赖的 Swoole 扩展预编译二进制与新版 libc 不兼容，表现为容器内 php -m | grep swoole 无输出，或启动时报 undefined symbol: SSL_CTX_set_ciphersuites。
稳妥做法是明确指定旧版：
wsl --install -d Ubuntu-22.04
安装完成后进入终端，顺手升级基础工具：
sudo apt update && sudo apt install -y curl git unzip net-tools
这能避免后续 Docker Desktop 检测 WSL 发行版时因缺少 curl 而静默失败。
docker run 启动 Hyperf 容器时必须加 --privileged 和 -u root
Hyperf 在开发模式下需监听 9501 端口、读写 /proc 获取进程信息、调用 inotify 监控文件变化——这些操作在默认非特权容器中会被 SELinux 或 Capabilities 限制。不加 --privileged 可能出现：
-
php bin/hyperf.php start启动后立即退出，日志无报错 -
hyperf/watcher无法触发热重启，inotify_add_watch返回 -1 - MySQL/Redis 连接超时，实际是容器内 DNS 解析失败（
--privileged开启 full capabilities 后才能正常使用 systemd-resolved）
完整推荐命令（路径按你本地调整）：
docker run -d --name hyperf -v D:\project\hyperf:/data/project -p 9501:9501 -it --privileged -u root --entrypoint /bin/sh hyperf/hyperf:8.1-alpine-v3.12-swoole
注意：不要用 alpine-v3.11-swoole 镜像配 PHP 8.1，Swoole 4.8+ 对 Alpine 3.11 的 musl 版本有已知 segfault 风险。
容器内首次执行 composer create-project 前必须设阿里云镜像
Hyperf 项目依赖较多（如 psr/log、symfony/var-dumper），在未换源情况下，composer create-project hyperf/hyperf-skeleton 极易卡在「Installing dependencies from lock file」阶段，甚至超时中断导致 vendor 不完整。这不是网络抖动，而是 Packagist 官方源对国内 IP 限速。
进入容器后第一件事不是 cd，而是立刻配置镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer
验证是否生效：
composer config -g repo.packagist → 应输出 https://mirrors.aliyun.com/composer
之后再执行：
cd /data/project && composer create-project hyperf/hyperf-skeleton
若已误操作导致 vendor 残缺，别删重来，直接进项目目录运行：
composer install --no-dev
再补装开发组件：composer require hyperf/watcher -dev。
