如何在Windows 11通过WSL2搭建原生PHP开发环境集成Ubuntu与Visual Studio Code

在Windows 11系统中，通过WSL2搭建原生PHP开发环境，能够同时兼顾Windows的易用性和Linux的开发适配性，搭配Ubuntu系统和Visual Studio Code可以大幅提升PHP开发效率。这种方式不需要额外安装第三方集成环境，所有组件都可以通过官方渠道获取，稳定性和兼容性都有保障。

前置条件准备

首先需要确认你的Windows 11系统版本符合要求，建议升级到最新正式版，同时需要开启系统的虚拟化功能，一般现代CPU都支持该特性，可以在BIOS中开启虚拟化选项。

启用WSL2功能

以管理员身份打开PowerShell，执行以下命令启用WSL相关功能：

# 启用适用于Linux的Windows子系统
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 启用虚拟机平台功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完成后重启电脑，然后下载并安装WSL2内核更新包，安装完成后在PowerShell中执行以下命令将WSL默认版本设置为2：

wsl --set-default-version 2

安装Ubuntu系统

打开Microsoft Store，搜索Ubuntu，选择最新的LTS版本点击安装，安装完成后启动Ubuntu，按照提示设置用户名和密码，等待系统初始化完成。

Ubuntu中配置PHP环境

进入Ubuntu终端后，首先更新软件源：

sudo apt update
sudo apt upgrade -y

安装PHP及常用扩展

Ubuntu默认软件源中的PHP版本可能不是最新，我们可以先添加PHP官方源再安装：

# 安装软件源管理工具
sudo apt install software-properties-common -y
# 添加PHP官方源
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
# 安装PHP8.2及常用扩展，可根据需求调整版本和扩展
sudo apt install php8.2 php8.2-cli php8.2-fpm php8.2-mysql php8.2-curl php8.2-xml php8.2-mbstring php8.2-zip -y

安装完成后执行php -v可以查看PHP版本，确认安装成功。

配置PHP-FPM

PHP-FPM的配置文件位于/etc/php/8.2/fpm/pool.d/www.conf，可以根据需求修改监听端口或者用户权限，一般默认配置即可满足开发需求。启动PHP-FPM服务：

sudo systemctl start php8.2-fpm
sudo systemctl enable php8.2-fpm

安装配置Visual Studio Code

在Windows 11中下载安装Visual Studio Code，安装完成后打开扩展面板，搜索并安装以下两个核心扩展：

• WSL：用于连接WSL2中的Ubuntu系统
• PHP Intelephense：提供PHP代码智能提示、跳转定义等功能
• PHP Debug：用于PHP代码调试

连接WSL2环境

点击Visual Studio Code左下角的绿色按钮，选择连接到WSL，等待连接完成后，打开Ubuntu中的项目目录，就可以直接在Windows端编辑Linux环境中的PHP文件。

配置PHP调试环境

在Ubuntu中安装Xdebug扩展：

sudo apt install php8.2-xdebug -y

然后修改Xdebug的配置文件/etc/php/8.2/mods-available/xdebug.ini，添加以下配置：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

重启PHP-FPM使配置生效：

sudo systemctl restart php8.2-fpm

在Visual Studio Code中打开PHP项目，创建.vscode/launch.json文件，添加以下调试配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

验证环境可用性

在Ubuntu的/home/你的用户名/目录下创建test.php文件，写入以下测试代码：

<?php
phpinfo();
?>

在Visual Studio Code中打开该文件，按下F5启动调试，然后在浏览器中访问WSL2的IP地址加上文件路径，就可以看到PHP信息页面，同时断点调试功能也可以正常使用，说明整个原生PHP开发环境搭建完成。

常见问题处理

如果WSL2无法启动，可以检查是否开启了虚拟化功能，或者重新安装WSL2内核更新包。如果Visual Studio Code无法连接WSL2，可以尝试在PowerShell中执行wsl --shutdown命令重启WSL服务后再尝试连接。如果Xdebug无法触发断点，可以检查端口是否被占用，以及Xdebug配置中的客户端地址是否正确。

WSL2UbuntuPHPVisual_Studio_Code修改时间：2026-07-18 06:12:26