WSL2+Ubuntu+VS Code可跑原生PHP环境，但需确保PHP进程由WSL2托管、路径统一、调试直连；推荐Ubuntu 24.04手动导入，更新内核、修复权限与头文件路径，VS Code必须用Remote-WSL打开项目并配置正确PHP路径。
直接用 WSL2 + Ubuntu + VS Code 能跑起原生 PHP 开发环境，但关键不在“能装”，而在「PHP 进程是否由 WSL2 内部托管、文件路径是否跨系统一致、调试是否直连」——这三点没对齐，VS Code 的 PHP Debug、Xdebug、Composer 自动补全都会掉链子。
WSL2 发行版选 Ubuntu 24.04 而非 Windows 商店默认版本
微软商店里点几下安装的 Ubuntu（如 Ubuntu 22.04 或 Ubuntu 24.04）默认使用 wsl --install 流程，会跳过内核手动更新和默认用户配置，导致后续 php-fpm 启动失败或权限报错。必须改用命令行方式指定发行版并确认内核绑定：
- 先执行
wsl --update确保内核是最新版（2026 年 4 月已到 5.15.153.1+） - 卸载商店安装的旧实例：
wsl --unregister Ubuntu - 从官方镜像手动导入：
wsl --import Ubuntu-24.04 C:wslubuntu-2404 ubuntu-24.04.tar.gz --version 2（镜像需提前下载） - 启动后运行
sudo usermod -aG www-data $USER，否则/var/run/php/目录权限会卡住 FPM 启动
编译安装 PHP 8.4 时绕开 OpenSSL 和 GD 头文件路径陷阱
Ubuntu 24.04 自带 OpenSSL 3.x，但 PHP 8.4 编译时若不显式指定旧版头文件位置，./configure 会静默跳过 --with-openssl，导致后续 cURL、JWT、PDO MySQL SSL 连接全部失效。GD 库同理，libjpeg-dev 安装后头文件实际在 /usr/include/x86_64-linux-gnu/jpeglib.h，但 configure 默认只扫 /usr/include。
- 先建软链修复路径：
sudo ln -s /usr/include/x86_64-linux-gnu/jpeglib.h /usr/include/jpeglib.h - 编译时强制指定 OpenSSL 路径：
--with-openssl=/usr/lib/x86_64-linux-gnu -
make -j$(nproc)前务必加export MAKEFLAGS="-j$(nproc)"，否则 WSL2 下 make 会因 CPU 调度抖动卡死 - 安装完执行
/usr/local/php8.4/bin/php -m | grep -E 'openssl|gd|curl'验证模块是否真实加载
VS Code 必须用 Remote-WSL 插件打开项目，且禁用 Windows 版 PHP 扩展
如果你在 Windows 系统里装了 PHP（比如通过 XAMPP 或官网二进制包），VS Code 的 PHP Intelephense 或 PHP Debug 插件会优先读取 php.exe 路径，而不是 WSL2 里的 /usr/local/php8.4/bin/php。结果就是：代码提示走 Windows PHP 8.2，而终端里 php -v 显示的是 WSL2 的 8.4，调试断点永远不触发。
立即学习“PHP免费学习笔记（深入）”；
- 彻底卸载 Windows 本地 PHP，或至少把它的目录从系统
PATH中移除 - 在 VS Code 中用
Ctrl+Shift+P→Remote-WSL: New Window打开项目，确保左下角显示WSL: Ubuntu-24.04 - 设置里搜索
php.executablePath，设为/usr/local/php8.4/bin/php（注意是 WSL2 内路径，不是\wsl$Ubuntu-24.04usrlocal...） - 禁用所有非 Remote-WSL 环境下的 PHP 插件，只保留 Remote-WSL、PHP Intelephense（Remote 模式）、PHP Debug（需额外配
launch.json指向 WSL2 的php和xdebug）
文件系统互通不能直接用 /mnt/c/ 存项目
把 PHP 项目放在 /mnt/c/Users/xxx/project 下看似方便，但 WSL2 对 NTFS 挂载点的 inotify 支持极差——Composer install、Vite HMR、甚至 php-fpm -R 的配置热重载都会失效。Windows 文件系统层没有真正的 inode 变更通知，inotifywait -m -e modify,create /mnt/c/... 基本收不到事件。
- 项目根目录必须放在 WSL2 原生文件系统中，例如
~/workspace/myapp - VS Code Remote-WSL 打开时自动挂载该路径，Windows 资源管理器可通过
\wsl$Ubuntu-24.04homeyournameworkspace访问，只是别在这里改文件 - 如果必须同步 Windows 侧文件（如设计稿、文档），用
rsync -av --delete ~/workspace/myapp/ /mnt/c/Users/xxx/sync/定期推，而非实时挂载
最常被忽略的一点：WSL2 的 /etc/resolv.conf 默认由 Windows DNS 接管，但某些 PHP Composer 镜像源（如阿里云、腾讯云）在 WSL2 里会因 DNS 解析超时直接 fallback 到 slow default，导致 composer create-project 卡住十分钟。需要手动在 /etc/wsl.conf 加 [network] generateResolvConf = false，再重生成 resolv.conf 并填入可靠 DNS（如 nameserver 223.5.5.5）。
