Docker(WSL2)环境下Yasd调试Laravel Octane(Swoole)报错问题

问题现象 #

基于Laravel Sail构建的Swoole Laravel项目，使用Yasd扩展调试时出现三类异常，运行环境为Windows 10 + WSL2 + 与WSL共享的Windows版Docker Desktop，项目镜像由sail artisan sail:publish生成的Dockerfile构建，IDE为VSCode搭配PHP Debug扩展，初始调试配置如下：

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

三类异常表现：

• 配置yasd.remote_host="host.docker.internal"时，容器启动后PHP进程直接退出，报错Invalid address/ Address not supported: Inappropriate ioctl for device
• 配置yasd.remote_host为Windows侧固定IP192.168.65.2并开启VSCode调试监听时，容器启动后卡住无响应，日志停留在PHP进程进入RUNNING状态的提示
• 上述IP配置下关闭VSCode调试监听，PHP进程直接退出，报错[yasd] recv command error, connection closed

根因说明 #

1. 域名解析失败：Yasd为C实现的Swoole调试扩展，在PHP初始化阶段就会解析远程调试地址，底层不支持host.docker.internal这类域名格式，仅识别纯IPv4地址，直接配置域名会触发地址无效错误。
2. 端口冲突：9000为Laravel Sail环境中PHP-FPM的默认监听端口，与调试端口冲突，导致调试连接无法正常建立。
3. 网络连通性问题：WSL2+Docker Desktop架构下，固定写死的WSL虚拟IP会随WSL重启变动，且Windows防火墙默认拦截来自Docker网段的入站请求；若防火墙丢包会导致TCP握手阻塞，表现为容器卡住，若直接拒绝连接则表现为Yasd连接断开进程退出。
4. 路径映射失效：若未通过Remote-WSL扩展打开WSL内的项目目录，${workspaceRoot}会读取到Windows格式路径，与容器内Linux路径无法匹配，即使连接成功也无法正常命中断点。

修复步骤 #

1. 调整Yasd基础配置 #

编辑docker/8.1/yasd.ini，修改配置如下，避开端口冲突：

yasd=On
yasd.debug_mode=remote
yasd.remote_port=9003
yasd.log_level=0

9003为PHP调试生态通用默认端口，不会与PHP-FPM的9000端口冲突

2. 配置动态获取宿主机IP #

编辑docker/8.1/supervisord.conf中PHP进程的启动命令，在启动Swoole服务前自动读取容器默认网关（即宿主机可达IP）写入Yasd配置，无需每次重启手动修改IP：

[program:php]
command=/bin/sh -c "echo 'yasd.remote_host=$(ip route show default | awk '/default/ {print $3}')' >> /etc/php/8.1/cli/conf.d/yasd.ini && php /var/www/html/artisan octane:start --server=swoole --host=0.0.0.0 --port=80"
user=sail
environment=LARAVEL_SAIL="1"
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

3. 修正VSCode调试配置 #

修改launch.json，调整端口与路径映射规则：

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

项目必须存放在WSL2文件系统中，使用VSCode的Remote-WSL扩展打开WSL内的项目目录，禁止直接打开Windows挂载路径下的项目，否则路径映射会失效。

4. 添加防火墙放行规则 #

打开Windows Defender防火墙高级设置，新建入站规则：允许来自Docker默认网段172.16.0.0/12的9003端口TCP请求，避免调试连接被防火墙拦截。

5. 重建容器验证 #

执行以下命令重建镜像并启动容器：

sail down
sail build --no-cache
sail up -d

先点击VSCode调试面板的监听按钮，再访问应用接口即可正常触发断点。

内容的提问来源于stack exchange，提问作者Den