php -- wsl2 + vscode 的 debug 环境搭建php5.6 + xdebug + vscode。本文

概述

最近(2025年)接手了公司一个十多年前的项目，技术栈是 php5.6 + bootstrap 前后端一体。本文记录了在 WSL2（Ubuntu 22.04）环境下搭建 PHP 5.6 开发环境，并配置 Xdebug 实现 VSCode 远程调试的完整流程。通过本环境，开发者可以在 Windows 系统上使用 WSL2 运行 PHP 应用，并通过 VSCode 的进行代码调试。

详细步骤

1. PHP 5.6 环境搭建

1.1 添加 PHP 5.6 源

sudo add-apt-repository ppa:ondrej/php
sudo apt update

1.2 安装 PHP 5.6 及相关扩展

sudo apt install -y php5.6 php5.6-fpm php5.6-cli php5.6-common php5.6-mysql php5.6-zip php5.6-gd php5.6-mbstring php5.6-curl php5.6-xml php5.6-bcmath

验证方法：

php -v

输出应显示 PHP 5.6.x 版本信息。

systemctl status php5.6-fpm

输出 php5.6-fpm service 信息。

本项目通过 9000 端口暴露服务，更新 /etc/php/5.6/fpm/pool.d/www.conf 更新 listen 配置 listen = 127.0.0.1:9000 并重启。

listen = 127.0.0.1:9000

重启服务，检查 9000 端口监听正常：

sudo systemctl restart fpm5.6-fpm
sudo lsof -i:9000

2. Nginx 安装与配置

2.1 安装 Nginx

sudo apt install nginx

2.2 配置 Nginx

创建站点配置文件：

sudo nano /etc/nginx/conf.d/test.conf

添加以下配置：

server {
    listen 80;
    server_name localhost;
    # 更新为实际的项目路径
    root /var/www/html;
    index index.php index.html;

    # 按需配置各参数
    client_max_body_size 50M; # 设置为 50MB

    # 增加缓冲区大小
    proxy_buffer_size          10M;
    proxy_buffers              4 10M;
    proxy_busy_buffers_size    10M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        # php5.6-fpm 暴露端口
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        include fastcgi.conf;

        # 增加 FastCGI 缓冲区大小
        fastcgi_buffer_size 128k;
        fastcgi_buffers 4 256k;
        fastcgi_busy_buffers_size 256k;
    }
}

验证方法：

sudo nginx -t
sudo systemctl restart nginx

访问 http://localhost 应能看到 Nginx 欢迎页面。

3. Xdebug 配置

3.1 安装 Xdebug

# 注意版本保持一致
sudo apt install php5.6-xdebug

3.2 配置 Xdebug

检查 /etc/php/5.6/mods-available/xdebug.ini 文件，可以看到以下软链接：

/etc/php/5.6/cli/conf.d/20-xdebug.ini
find /etc/php/5.6/ -type l -lname '/etc/php/5.6/mods-available/xdebug.ini'
/etc/php/5.6/apache2/conf.d/20-xdebug.ini
/etc/php/5.6/fpm/conf.d/20-xdebug.ini
/etc/php/5.6/cli/conf.d/20-xdebug.ini

通过 php -i | grep xdebug 可以看到 Xdebug 相关参数输出，即表示安装成功。

接下来，更新 /etc/php/5.6/mods-available/xdebug.ini，添加以下配置：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.remote_enable=true
xdebug.start_with_request=yes
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9003
xdebug.idekey=VSCODE
xdebug.log=/var/log/xdebug.log
xdebug.remote_autostart=1

验证方法：重启 sudo systemctl restart php5.6-fpm，检查参数生效：

php -i | grep xdebug

应能看到 Xdebug 相关信息。

4. VSCode 配置

4.1 安装必要扩展

PHP Debug
Remote - WSL

4.2 配置调试设置

创建 .vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

验证方法：

在 VSCode 中打开 WSL 下的项目文件夹
设置断点
启动调试会话
访问对应的 PHP 页面，断点应该被触发

常见问题排查

1. Xdebug 连接问题

检查 Xdebug 日志
确认端口 9003 未被占用

2. PHP-FPM 问题

检查 PHP-FPM 状态：sudo systemctl status php5.6-fpm
查看错误日志：/var/log/php5.6-fpm.log

3. Nginx 配置问题

检查 Nginx 错误日志：/var/log/nginx/error.log
验证配置文件语法：sudo nginx -t

总结

通过以上步骤，我们成功搭建了一个完整的 PHP 开发调试环境。该环境具有以下特点：

PHP 5.6 提供稳定的运行环境
Nginx 提供高性能的 Web 服务器
Xdebug 实现强大的调试功能
VSCode 提供便捷的开发体验