一、前置准备：开启并安装 WSL2（核心步骤）
- 按下
Win + R，输入optionalfeatures回车，打开「Windows 功能」；- 勾选以下 3 个选项（无则跳过），点击「确定」，等待安装完成后重启电脑 ：
- 适用于 Linux 的 Windows 子系统
- 虚拟机平台
- Windows 虚拟机监控程序平台
- 前置检查重启后，WSL2 基础环境已开启。
二、前置检查
按下 Win + R 输入 cmd 打开管理员 CMD（右键 CMD 选「以管理员身份运行」），执行以下命令，检查 WSL 是否已开启：
wsl --status若显示「默认版本：2」,说明启动 WSL2 成功
三、一键安装 Ubuntu 22.04 LTS（WSL2 版）
wsl --install -d Ubuntu-24.04
- 命令执行后，系统自动下载并安装 Ubuntu 22.04，全程无需操作，等待5 分钟内完成（进度条在终端显示）；
- 安装完成后，终端会自动弹出 Ubuntu 初始化窗口，提示设置 Linux 用户名和密码 （关键步骤）：
- 提示
Enter new UNIX username:：输入自定义用户名（如phpdev、hyperf，纯字母 / 数字，无需和 Windows 用户名一致），回车；- 提示
Enter new UNIX password:：输入密码（输入时屏幕无任何显示，是 Linux 安全机制，正常输入即可），回车；- 提示
Retype new UNIX password:：再次输入相同密码，回车；- 后续出现的配置提示，全部按回车默认即可，初始化完成后直接进入 Ubuntu 22.04 命令行。
四、验证安装结果
wsl -l -vNo LSB modules are available.
Distributor ID: Ubuntu Description:
Ubuntu 22.04.1 LTS Release: 22.04
Codename: noble
说明成功
五、后续快速打开 Ubuntu 22.04 的方式
- 快捷方式 ：按下
Win + S，搜索「Ubuntu 22.04 LTS」，点击即可打开，无需每次用 CMD；- Windows 终端：打开 Windows 自带的「终端」，点击顶部下拉箭头，选择「Ubuntu 22.04 LTS」，可多标签同时操作 Windows 和 Linux。
六、Ubuntu 22.04 LTS 系统更新 + 安装 PHP 8.2 及核心依赖
# 步骤 1：更新 Ubuntu 软件源
sudo apt update && sudo apt upgrade -y
# 步骤 2：安装 PHP8.2 及基础扩展（CLI 版本，适配服务运行）
sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-curl php8.2-mbstring php8.2-zip php8.2-gd
# 步骤 3：安装 PHP8.2 关键扩展（Hyperf 必备）
sudo apt install -y php8.2-xml php8.2-bcmath php8.2-sockets
# 步骤 4：安装 Pecl 扩展管理器（用于安装 Swoole/Redis 等扩展）
sudo apt install -y php-pear php8.2-dev gcc make七、安装 Hyperf 核心依赖：Swoole 5.1.1 + Redis 扩展
# 步骤 1：安装 Swoole 5.1.1 扩展（Hyperf 核心，协程 / HTTP2 支持）
# 安装过程中所有询问（如 Enable OpenSSL/HTTP2），直接按回车选默认；
sudo pecl install swoole-5.1.1
# 安装完成后，写入 PHP 配置让扩展生效
echo "extension=swoole.so" | sudo tee /etc/php/8.2/cli/conf.d/20-swoole.ini
步骤 2：验证 Swoole 安装成功
php --ri swoole
# 显示 Swoole 版本、协程 / HTTP2 等特性为 enabled 即成功。
# 步骤 3：安装 PHP Redis 扩展（Hyperf Redis 组件依赖）
sudo pecl install redis
# 安装完成后写入配置
echo "extension=redis.so" | sudo tee /etc/php/8.2/cli/conf.d/20-redis.ini
# 步骤 4：验证所有核心扩展
php -m | grep -E "swoole|redis|xml|bcmath|gd"
# 输出所有扩展名称即说明安装并加载成功。八、安装 Composer 并配置国内源（加速依赖下载）
# 步骤 1：安装 Composer
php - r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php - r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer
# 步骤 2：配置阿里云 Composer 国内源
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
# 步骤 3：验证 Composer 安装
composer -V
# 显示 Composer 版本号即成功。九、创建 Hyperf 3.X 项目并解决依赖问题
# 步骤 1：创建 Hyperf 3.X 骨架项目
composer create-project hyperf/hyperf-skeleton hyperf3-demo "3.*"
- 执行后出现交互式询问：
- 时区：输入
Asia/Shanghai回车；- 数据库：选
y回车（安装 MySQL 相关组件）；- Redis：选
y回车（安装 Redis 相关组件）；- 其余 RPC / 配置中心 / 队列等组件：均选
n回车（基础开发暂无需）；- 若出现「ext-redis 缺失」报错，说明 Redis 扩展未生效，重新执行步骤三的 Redis 配置命令即可。
# 步骤 2：进入项目目录并补全依赖
php bin/hyperf.php start启动成功标识：终端输出
HTTP Server listening at 0.0.0.0:9501+ 多个Worker#N started.日志，无任何报错。
打开浏览器，地址栏输入：
http://127.0.0.1:9501显示 Hyperf Welcome 欢迎页即说明服务启动成功，WSL2 与 Windows 端口映射正常。
十、打开 WSL2 项目目录
- 按下
Win+E打开 Windows 文件资源管理器；- 点击顶部地址栏 ，输入
\\wsl$按下回车；- 依次双击文件夹：
Ubuntu-22.04→home→ 你的 Ubuntu 用户名（如mo）→hyperf3-demo；- 打开的
hyperf3-demo文件夹即为 Hyperf 项目根目录，所有代码直接在此编辑。
十一、其他
停止服务
Ctrl + C
重新启动服务
cd ~/hyperf3-demo && php bin/hyperf.php start