Xdebug 3 在 Docker 容器中与 VSCode 协同调试指南

本文详细介绍了如何在 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 扩展并将其配置文件复制到正确的位置。

面试猫

AI面试助手，在线面试神器，助你轻松拿Offer

39

查看详情

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. 启动与调试流程

1. 构建并启动 Docker 容器：

   docker-compose up --build -d

   登录后复制
2. 在 VSCode 中启动监听： 打开 launch.json，选择 "Listen for Xdebug" 配置，点击调试按钮（或按 F5）。VSCode 将开始监听 9003 端口。
3. 触发 PHP 请求： 在浏览器中访问你的应用（例如 localhost:8001），Xdebug 将根据 xdebug.start_with_request = yes 的设置自动尝试连接到 VSCode 调试器。
4. 设置断点： 在 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 开发效率。

以上就是Xdebug 3 在 Docker 容器中与 VSCode 协同调试指南的详细内容，更多请关注php中文网其它相关文章！