VSCode - 搭建PHP开发环境详细教程（附Xdebug调试环境配置）

作者：hangge | 2026-06-15 09:42

相比传统 IDE，VS Code 具有轻量、启动快、插件丰富等优点，非常适合作为 PHP 开发工具。本文将通过实际操作演示如何搭建 PHP 开发环境，涵盖语言智能提示、代码格式化、断点调试、本地服务器等核心能力。

1，安装 PHP

（1）访问 PHP 官网下载页（点击访问），下载最新稳定版，注意选择 Thread Safe (TS) 版本的 Zip 压缩包，x64 架构。

（2）将压缩包解压到纯英文路径，例如 D:\php\php8.5，路径中不要包含空格和中文。

（3）PHP 根目录中默认没有 php.ini，将 php.ini-development 复制一份，重命名为 php.ini。

（4）打开 php.ini，修改以下常用配置：

; 扩展目录（确保路径正确）
extension_dir = "ext"

; 开启常用扩展（去掉前面的分号）
extension=curl
extension=gd
extension=mbstring
extension=mysqli
extension=pdo_mysql
extension=openssl

; 设置时区
date.timezone = Asia/Shanghai

（5）配置环境变量

右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
在「系统变量」中找到 Path，点击「编辑」→「新建」
填入 PHP 根目录路径，例如 D:\php\php8.5
逐级点击确定保存

（5）打开命令提示符（Win + R 输入 cmd），执行如下命令。若输出版本号信息则说明安装成功。

php -v

2，VS Code 核心插件安装

（1）打开 VS Code，首先搜索安装 PHP Intelephense 插件。这是目前性能最好的 PHP 语言服务器（LSP），提供智能代码补全、定义跳转、符号搜索、重构、错误诊断等功能，远优于 VS Code 内置的 PHP 支持。

安装后建议在 settings.json 中关闭内置 PHP 提示以避免冲突：

{
    "php.validate.enable": false,
    "php.suggest.basic": false,
    "intelephense.environment.phpVersion": "8.3",
    "intelephense.format.enable": true
}

（2）接着安装 PHP Debug 这个插件，它是官方调试适配器，配合 Xdebug 扩展实现断点调试、变量查看、单步执行等功能。这是 VS Code 调试 PHP 的核心插件，后文会详细讲解配置方法。

（3）然后安装 PHP Server 插件，它可以一键启动 PHP 内置开发服务器，无需安装 Apache/Nginx 即可快速预览 PHP 页面。右键 PHP 文件选择“PHP Server: Serve project”即可在浏览器中打开。

（4）还有如下一些实用插件，大家可以根据情况进行安装：

PHP DocBlocker：快速生成 PHPDoc 注释，输入 /** 按回车自动补全参数和返回值
PHP CS Fixer：代码格式化工具，统一代码风格
EditorConfig for VS Code：团队协作时统一编辑器配置
Composer：PHP 依赖管理工具集成
MySQL：数据库管理插件，可直接在编辑器中操作数据库

3，使用测试

（1）新建文件夹 php-demo，用 VS Code 打开，新建 index.php，代码如下：

<?php
function greet(string $name): string
{
    $message = "hello, " . $name;
    return $message;
}

$user = "hangge.com";
$result = greet($user);

echo $result;
phpinfo();

（2）要运行程序有三种方式：

第 1 种是右键 index.php 内容区域，选择右键菜单项“PHP Server: Serve project”，便会自动打开浏览器访问 http://localhost:3000/index.php

第 2 种是在命令行种进入项目目录，然后执行如下命令启动 PHP 内置服务器：

php -S localhost:8080

第 3 种是在命令行直接运行如下命令，执行指定的 php 文件代码。

php index.php

（3）第一、二种方法运行后，使用浏览器访问效果如下（第三种结果直接在控制台输出）：

附：Xdebug 3 调试环境配置

1，下载 Xdebug 扩展

（1）在命令行执行如下命令，查看并复制当前 PHP 环境信息：

php -i

（2）打开 Xdebug 官方向导（点击访问），将复制上面全部输出，粘贴到官方向导文本框中，页面会自动分析并给出匹配的 DLL 文件下载链接和安装指引。

（3）下载 .dll 文件，重命名为 php_xdebug.dll，放入 PHP 的 ext 目录中。

2，配置 php.ini

（1）打开 php.ini，在文件末尾添加以下配置，关键参数说明如下：

xdebug.mode = debug：启用调试模式，Xdebug 3 必须显式指定
xdebug.start_with_request = yes：每次请求自动启动调试，新手推荐；熟练后可改为 trigger 按需触发
xdebug.client_port = 9003：Xdebug 3 默认端口，注意不是旧版的 9000

[XDebug]
zend_extension = xdebug
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.idekey = VSCODE

（2）保存后重启命令行，执行如下命令。如果输出包含 with Xdebug v3.x.x 字样，则说明 Xdebug 加载成功。

php -v

3，配置 VS Code 调试器

（1）在 VS Code 中打开我们的 PHP 项目文件夹，点击左侧“运行和调试”图标，选择“创建 launch.json 文件”。

（2）环境选择“PHP”，自动生成配置文件

（3）修改 .vscode/launch.json 内容如下：

注意：port 必须与 php.ini 中的 xdebug.client_port 保持一致，否则无法连接。如果使用 Docker 或远程服务器，需要在 pathMappings 中配置服务器路径与本地路径的映射关系。

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

4，开始调试

（1）在 PHP 代码行号左侧点击，设置红色断点。

（2）按 F5 启动调试监听，底部状态栏变色。

（3）通过浏览器访问对应的 PHP 页面（或用 PHP Server 启动）代码执行到断点处会自动暂停

VS Code 左侧可查看变量、调用栈
使用 F10 单步跳过、F11 单步进入、F5 继续执行

其他