关键在于PHPStorm、Yasd、容器网络和代码路径四者对齐；需安装Yasd、正确配置路径映射、暴露9003端口、设环境变量YASD_CONFIG，并在业务层设断点且请求带X-DEBUG:1。
在Docker容器中调试Hyperf项目，关键不是“能不能断点”，而是让PHPStorm、Yasd（或Xdebug）、容器网络和代码路径四者对齐。Windows环境下尤其要注意路径映射和调试协议穿透问题。
确保容器内已装好Yasd并启用调试支持
Yasd是Swoole生态推荐的调试器，比Xdebug更适配协程环境。构建镜像时需显式安装：
- 基础镜像建议用
hyperf/hyperf:8.2-alpine-v3.18-swoole或自建PHP 8.2+ Alpine镜像 - 安装依赖：
apk add --no-cache boost-dev openssh-server - 编译安装Yasd（官方推荐方式）：
git clone https://github.com/swoole/yasd.git /tmp/yasd && cd /tmp/yasd && ./configure && make && make install - 启用扩展：
echo "extension=yasd.so" >> /usr/local/etc/php/conf.d/docker-php-ext-yasd.ini - 确认生效：
php -m | grep yasd应输出yasd
PHPStorm配置：服务映射 + 调试监听必须匹配
Windows宿主机与Linux容器之间存在路径差异，PHPStorm靠“路径映射”识别断点位置：
- 在Preferences → PHP → Servers中新增服务器，名称任意，Host填
localhost，Port填容器暴露端口（如9501） - 关键一步：勾选Use path mappings，然后映射本地项目目录（如
D:\project\hyperf）→ 容器内对应路径（如/home/carver-hyperf） - 调试配置选PHP Web Page或PHP Remote Debug，Server选刚建的，IDE key填
PHPSTORM - 启动调试前，确保PHPStorm右上角电话图标为绿色（已监听9003端口）
容器启动时开放调试端口并传递必要参数
仅暴露HTTP端口（9501）不够，Yasd默认通过9003与IDE通信，需额外暴露并设置环境变量：
- docker-compose.yml中添加：
ports: ["9003:9003"] - 添加环境变量：
YASD_CONFIG='{"host":"0.0.0.0","port":9003,"enable":true}' - 若用
docker run，加参数：-p 9003:9003 -e YASD_CONFIG='{"host":"0.0.0.0","port":9003,"enable":true}' - 注意：Hyperf启动命令保持为
php bin/hyperf.php start，无需改用--debug——Yasd会自动注入
断点位置有讲究：避开协程调度盲区
Hyperf基于Swoole协程，部分代码（如Worker进程初始化、协程上下文切换逻辑）无法稳定命中断点：
- 优先在
app/Controller、app/Service等业务层设断点，成功率最高 - 避免在
bin/hyperf.php顶层入口或config/autoload/processes.php中设断点 - 若调试HTTP请求，确保请求头带
X-DEBUG: 1（Yasd默认需要该Header触发调试会话） - 可临时加日志验证：
var_dump(yasd_is_enabled());输出true表示Yasd已就绪
