PHP 8.4.1在WSL2中需通过Ondřej Surý的PPA安装，而非官方源；须装php8.4及mysql/pgsql等扩展并验证模块加载；数据库连接推荐WSL2内MySQL并改root认证方式，避免权限失败。
要在 Windows 的 WSL2 中搭建 PHP 8.4.1 开发环境，核心不是“装完就通”，而是理清三件事：PHP 8.4.1 怎么精准获取、它依赖的扩展是否齐全、以及它能否稳定连接你选用的数据库（如 MySQL 或 PostgreSQL）。整个过程建议全部在 WSL2 Ubuntu 原生路径（如 ~/projects）中完成，避免使用 /mnt/c 路径，防止权限和 inode 问题。
一、确认并初始化 WSL2 环境
确保已启用 WSL2 并运行 Ubuntu（推荐 22.04 或 24.04 LTS）：
- 以管理员身份打开 PowerShell，执行：wsl --install（自动启用子系统与虚拟机平台）
- 重启后运行：wsl --set-default-version 2，再用 wsl -l -v 验证状态为 Running 且版本为 2
- 首次启动 Ubuntu，设置普通用户（非 root），后续所有操作均用该用户执行
- 更新基础系统：sudo apt update && sudo apt upgrade -y
二、安装 PHP 8.4.1（官方 PPA 支持）
Ubuntu 官源不提供 PHP 8.4，必须通过 Ondřej Surý 的 PPA 获取。注意：截至 2026 年 10 月，ppa:ondrej/php 已正式支持 PHP 8.4：
- 安装必要工具：sudo apt install -y software-properties-common lsb-release ca-certificates
- 添加 PPA 并更新：sudo add-apt-repository ppa:ondrej/php -y && sudo apt update
- 安装 PHP 8.4 及常用扩展：sudo apt install -y php8.4 php8.4-cli php8.4-mysql php8.4-pgsql php8.4-sqlite3 php8.4-curl php8.4-mbstring php8.4-xml php8.4-zip php8.4-opcache
- 验证安装：php -v 应输出 PHP 8.4.1；php -m | grep -E "(mysql|pdo|curl)" 应显示 mysqli、pdo_mysql、curl 等模块
三、配置 Web 服务与开发调试支持
PHP CLI 已就绪，但开发还需运行时支撑。推荐轻量可靠方案：
立即学习“PHP免费学习笔记（深入）”；
- 内置服务器（适合快速验证）：进入项目目录，运行 php -S localhost:8000 -t public/（假设入口在 public/index.php）
- 搭配 Nginx（生产贴近）：安装 sudo apt install nginx-full -y，配置 /etc/nginx/sites-available/myapp，启用站点并重启 Nginx；PHP-FPM 使用 php8.4-fpm 包（会随 php8.4 自动安装）
- VS Code 调试集成：安装 PHP Debug 插件，在 WSL 中打开项目（路径为 /home/youruser/projects/myapp），PhpStorm 或 VS Code 均可自动识别 /usr/bin/php8.4 为解释器
四、连接数据库（以本地 MySQL 为例）
若 MySQL 运行在 WSL2 内部（推荐）：
- 安装：sudo apt install mysql-server -y
- 切换 root 认证方式（关键！否则 PDO 连接失败）：sudo mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_pass'; FLUSH PRIVILEGES;"
- 测试脚本 ~/test-pdo.php：
<?php $dsn = 'mysql:host=localhost;dbname=test;charset=utf8mb4'; try { $pdo = new PDO($dsn, 'root', 'your_pass', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC ]); echo "✅ PHP 8.4.1 + MySQL 连接成功\n"; print_r($pdo->query("SELECT VERSION()")->fetch()); } catch (PDOException $e) { echo "❌ 连接失败：" . $e->getMessage(); }
若 MySQL 运行在 Windows 主机上（如 phpEnv、XAMPP），则需将连接 host 改为 host.docker.internal（WSL2 不适用）或用网关 IP（grep nameserver /etc/resolv.conf | awk '{print $2}'），并在 Windows MySQL 中授权 'root'@'172.x.x.x' 并开放 bind-address = 0.0.0.0。
