本文详细介绍了如何在 docker 环境下配置 xdebug 3 与 vscode 进行 php 调试。内容涵盖 `docker-compose.yaml`、`dockerfile` 和 `xdebug.ini` 的正确设置，以及 vscode `launch.json` 的配置。特别强调了 `xdebug.ini` 文件命名和放置位置的关键性，并提供了常见问题排查建议，旨在帮助开发者构建稳定高效的调试工作流。
Xdebug 3 与 Docker 环境集成调试
在现代 PHP 开发中，利用 Docker 容器化应用已成为主流。为了在容器内实现高效的 PHP 代码调试，Xdebug 扮演着不可或缺的角色。本文将详细阐述如何配置 Xdebug 3，使其在 Docker 容器中与 VSCode 调试器无缝协作。
1. Xdebug 3 配置核心概念
Xdebug 3 相较于早期版本，引入了更简洁的配置项。以下是调试模式下几个关键的配置参数：
- xdebug.mode = debug: 启用调试模式。Xdebug 3 支持多种模式，debug 是最常用的。
- xdebug.start_with_request = yes: 指示 Xdebug 在每个请求开始时自动启动调试会话。这对于浏览器触发的调试非常方便。
- xdebug.client_port = 9003: 指定 Xdebug 客户端（即 VSCode 调试器）监听的端口。默认是 9003。
- xdebug.client_host = 'host.docker.internal': 这是在 Docker 容器内访问宿主机 IP 的推荐方式。它允许容器通过一个特殊的主机名直接连接到宿主机上的调试器。
- zend_extension = xdebug_extension: 加载 Xdebug 扩展。
2. Docker 环境配置
为了在 Docker 容器中运行 Xdebug，我们需要修改 Dockerfile 和 docker-compose.yaml。
2.1 docker-compose.yaml 配置
docker-compose.yaml 定义了服务、端口映射和卷挂载。确保 PHP 服务将应用代码挂载到容器内，并暴露必要的端口。
version: '2'
services:
php:
image: yiisoftware/yii2-php:7.4-apache
build:
context: .
dockerfile: Dockerfile
volumes:
- ~/.composer-docker/cache:/root/.composer/cache:delegated
- ./../../:/app:delegated # 将宿主机应用代码挂载到容器的 /app 目录
ports:
- '8001:80' # 将宿主机的 8001 端口映射到容器的 80 端口说明：
- volumes: 确保你的项目代码（例如 ./../../:/app）被正确挂载到容器中，这对于 pathMappings 至关重要。
- ports: 定义 Web 服务器的访问端口。
2.2 Dockerfile 配置
Dockerfile 负责安装 Xdebug 扩展并将其配置文件复制到正确的位置。
FROM yiisoftware/yii2-php:7.4-apache # 安装 Xdebug 扩展 RUN pecl install -f xdebug && docker-php-ext-enable xdebug # 复制 Xdebug 配置文件到 PHP 配置目录 # 关键点：确保文件名为 xdebug.ini，而不是 docker-php-ext-xdebug.ini COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini
关键注意事项： 在 PHP 的 FPM 或 Apache 环境中，PHP 会加载 /usr/local/etc/php/conf.d/ 目录下的所有 .ini 文件。虽然 docker-php-ext-enable xdebug 命令可能会生成一个名为 docker-php-ext-xdebug.ini 的文件，但直接将自定义的 xdebug.ini 文件命名为 xdebug.ini 并复制过去，可以避免潜在的配置覆盖或加载顺序问题，确保你的自定义配置生效。
2.3 xdebug.ini 配置
在你的项目根目录或 Dockerfile COPY 命令能访问到的地方创建 xdebug.ini 文件，并包含以下内容：
zend_extension = xdebug_extension [XDebug] xdebug.mode = debug xdebug.start_with_request = yes xdebug.client_port = 9003 xdebug.client_host = 'host.docker.internal' # 宿主机地址，用于 Docker Desktop xdebug.log = /tmp/xdebug.log # 启用 Xdebug 日志，方便排查问题
说明：
- xdebug.client_host: 对于 Docker Desktop 用户，host.docker.internal 是访问宿主机的标准方式。如果你使用的是 Linux 上的 Docker 或其他环境，可能需要替换为宿主机的实际 IP 地址（例如 172.17.0.1 或 $(ip -4 addr show docker0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')）。
- xdebug.log: 强烈建议在调试初期启用日志，它能提供 Xdebug 运行状态的详细信息，是排查问题的利器。
3. VSCode 调试器配置
VSCode 的 launch.json 文件定义了调试会话的启动方式。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003, // 必须与 xdebug.client_port 保持一致
"log": true, // 启用 VSCode 调试器日志
"pathMappings": {
"/app": "${workspaceRoot}" // 容器内代码路径到宿主机工作区路径的映射
},
"hostname": "0.0.0.0", // 监听所有网络接口
"xdebugSettings": {
"max_data": 65535,
"show_hidden": 1,
"max_children": 100,
"max_depth": 5
}
}
]
}关键配置项：
- port: 必须与 xdebug.client_port (在 xdebug.ini 中) 设置的端口一致。
- pathMappings: 这是 VSCode 能够正确映射容器内文件路径到宿主机工作区文件路径的关键。"/app" 是你的应用代码在 Docker 容器内的路径，${workspaceRoot} 是你的项目在 VSCode 中的根目录。
- log: 启用 VSCode 调试器的内部日志，有助于排查 VSCode 侧的问题。
4. 启动与调试流程
-
构建并启动 Docker 容器：
docker-compose up --build -d
- 在 VSCode 中启动监听： 打开 launch.json，选择 "Listen for Xdebug" 配置，点击调试按钮（或按 F5）。VSCode 将开始监听 9003 端口。
- 触发 PHP 请求： 在浏览器中访问你的应用（例如 localhost:8001），Xdebug 将根据 xdebug.start_with_request = yes 的设置自动尝试连接到 VSCode 调试器。
- 设置断点： 在 VSCode 中你的 PHP 代码行旁设置断点。当请求执行到断点时，VSCode 会暂停执行，允许你检查变量、单步调试等。
5. 常见问题排查
-
断点不生效：
- xdebug.ini 文件路径或命名错误： 确保 Dockerfile 中 COPY 命令将 xdebug.ini 复制到了正确的路径 (/usr/local/etc/php/conf.d/xdebug.ini)，并且文件内容无误。这是最常见的导致 Xdebug 不启动的原因。
- Xdebug 未加载： 进入容器内部 (docker exec -it <container_id> bash)，运行 php -m | grep xdebug 或 php -i | grep xdebug，确认 Xdebug 扩展已加载。
- xdebug.client_host 配置错误： 确保 host.docker.internal 能正确解析到宿主机 IP。如果不行，尝试使用宿主机的实际 IP 地址。
- pathMappings 配置错误： 检查 launch.json 中的 pathMappings 是否正确映射了容器内代码路径和宿主机工作区路径。
- 端口冲突： 确保 xdebug.client_port 和 launch.json 中的 port 端口一致，且宿主机上没有其他应用占用 9003 端口。
- 查看 Xdebug 日志： 在 xdebug.ini 中设置 xdebug.log = /tmp/xdebug.log。进入容器内部，查看 /tmp/xdebug.log 文件，它会记录 Xdebug 启动、连接尝试等详细信息，是诊断问题的最有效手段。
- VSCode 调试器日志： 在 launch.json 中设置 "log": true，VSCode 的调试控制台会输出调试器与 Xdebug 通信的日志，帮助分析 VSCode 侧的问题。
总结
通过上述步骤，你应该能够成功地在 Docker 容器中配置 Xdebug 3 并与 VSCode 进行调试。核心在于确保 Dockerfile 正确安装和配置 Xdebug，特别是 xdebug.ini 的命名和放置位置，以及 xdebug.client_host 和 VSCode pathMappings 的准确性。当遇到问题时，善用 Xdebug 日志和 VSCode 调试器日志将大大提高问题排查效率。构建一个稳定可靠的调试环境，将极大地提升 PHP 开发效率。
