Remote-WSL插件本身不提供PHP运行能力，它只是将VSCode桥接到WSL2的Linux环境；因此在Windows上通过WSL2运行PHP 8.3，本质是在WSL2发行版（如Ubuntu-22.04）中用apt安装PHP 8.3（非Windows版），再通过Remote-WSL连接开发，确保项目路径为Linux原生路径（如/home/user/project）、调试器指向/usr/bin/php，并正确配置Xdebug与php.ini。
Remote-WSL 插件本身不提供 PHP 运行能力，它只是把 VSCode 的编辑、终端、调试环境桥接到 WSL2 里的 Linux 环境中。所以“在 Windows 上通过 WSL2 运行 PHP 8.3”，本质是：先在 WSL2 发行版里装好 PHP 8.3（Linux 版），再用 Remote-WSL 连上去开发——不是 Windows 调用 PHP，也不是 WSL1 兼容层跑 PHP，而是真正在 Ubuntu/Debian 的用户空间里执行 php --version。
确认 WSL2 发行版已运行且为 v2
Remote-WSL 只支持 WSL2，不兼容 WSL1。常见错误如点击 WSL: New Window 后卡在 “Connecting to server…” 或报 WSL distribution not found，大概率是发行版没启动或版本不对。
- 在 PowerShell 中运行
wsl -l -v，确认目标发行版（如Ubuntu-22.04）状态为Running，VERSION 列为2 - 若为
Stopped，先执行wsl -d Ubuntu-22.04手动拉起 - 若 VERSION 是
1，运行wsl --set-version Ubuntu-22.04 2升级（需提前启用虚拟机平台） - 不要依赖开机自动启动 WSL——默认不启用，
/etc/wsl.conf中需显式配置[boot] command = true才能开机自启
在 WSL2 中安装 PHP 8.3（非 Windows 版）
Windows 官网已停止提供 PHP 8.0+ 的 Windows 二进制包，且扩展滞后、函数行为不一致。直接在 WSL2 里用 apt 安装官方维护的 PHP 8.3，才是生产对齐的做法。
- 进入 WSL2 终端（
wsl -d Ubuntu-22.04），更新源：sudo apt update && sudo apt upgrade -y - 添加 Ondřej Surý 的 PPA（Ubuntu 官方推荐）：
sudo apt install -y software-properties-common && sudo add-apt-repository ppa:ondrej/php -y && sudo apt update - 安装 PHP 8.3 及常用扩展：
sudo apt install -y php8.3 php8.3-cli php8.3-mbstring php8.3-xml php8.3-zip php8.3-curl php8.3-sqlite3 - 验证：
php --version应输出类似PHP 8.3.x (cli)；which php返回/usr/bin/php - 注意：不要把项目放在
/mnt/c/下——PHP 的opcache、文件锁、权限判断在/mnt/c中会失效或报错
VSCode 中用 Remote-WSL 正确打开项目并配置调试
路径选错是 PHP 调试失败最常见原因：VSCode 以“本地模式”打开 \wsl$\Ubuntu-22.04\home\user\project，会导致调试器找不到 php 解释器、composer 命令失效、vendor 权限异常。
立即学习“PHP免费学习笔记（深入）”；
- 必须从干净的 VSCode 窗口开始：不打开任何文件夹 →
Ctrl+Shift+P→ 输入WSL: New Window→ 选择发行版 - 然后
File > Open Folder…，路径选/home/user/project（Linux 风格绝对路径），左下角状态栏显示WSL: Ubuntu-22.04 - 调试前，在项目根目录建
.vscode/launch.json，关键字段：{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/home/user/project": "${workspaceFolder}" }, "log": true } ] } -
php.defaultInterpreterPath必须设为 WSL 内路径，例如/usr/bin/php或/usr/bin/php8.3，不能写C:\Users\...
避免 /mnt/c/ 路径 + 注意 Xdebug 配置位置
把 PHP 项目放在 /mnt/c/Users/xxx/project 表面省事，实则埋雷：WSL2 对 Windows 文件系统的权限模拟不可靠，chmod +x 失效、Git 报大量文件修改、opcache.validate_timestamps=Off 也救不了缓存失效问题。
- PHP 配置文件真实路径是
/etc/php/8.3/cli/php.ini（CLI 模式）和/etc/php/8.3/apache2/php.ini（Apache 模式），改错位置会导致phpinfo()和 CLI 输出不一致 - Xdebug 3 需手动启用：在
php.ini中添加zend_extension=xdebug.so xdebug.mode=debug xdebug.client_host=host.docker.internal xdebug.client_port=9003 xdebug.start_with_request=yes
- 如果用 Apache，记得重启服务：
sudo service apache2 restart；CLI 调试则无需重启，改完 ini 后php -v看是否加载了 xdebug
真正麻烦的不是装 PHP，而是让 VSCode 的调试器、终端、任务系统全部落在 WSL2 的同一套 PATH 和文件系统上下文中——一旦混用 Windows 路径或忽略 /mnt/c 的权限缺陷，后续所有调试、构建、测试都会出现看似随机的失败。
