微服务调用链调试需每个服务独立可调试、Xdebug会话标识跨服务透传、PhpStorm统一聚合日志与状态；否则无法定位断点未命中是因服务未收到请求还是调试未生效。
微服务调用链调试不能靠单个断点或一次 Debug 启动解决，必须让每个服务独立可调试、跨服务请求能携带 Xdebug 会话标识、且 PhpStorm 能统一聚合日志与状态——否则你永远在猜“是 user-service 没进断点，还是 order-service 根本没收到请求”。
每个微服务都要有独立的 PHP 运行配置
Services 面板不创建配置，只聚合已存在的运行项。如果你右键某个 artisan 文件点 Run，生成的是临时配置，无法并行启动、无法持久化环境变量、也无法被 Services 面板识别。
- 进入
Run | Edit Configurations→ 点击+→ 选PHP Script（Laravel）或Command Line Tool（Swoole/ThinkPHP） -
Script path必须指向该服务自己的启动入口，比如./user-service/artisan serve，不是整个 monorepo 的根目录 -
Working directory设为对应服务的根目录，例如./user-service，否则.env、config/都会加载错 - 勾选
Allow parallel run，否则启动第二个服务时第一个会自动终止 - 在
Environment variables中显式设置XDEBUG_MODE=debug和XDEBUG_CONFIG="client_host=127.0.0.1 client_port=9003"（Docker 容器内则填宿主机 IP）
Xdebug 请求头必须透传到下游服务
前端发起一个请求，经过 API 网关 → user-service → order-service，如果中间任何一跳没把 Xdebug 的上下文传下去，断点就只在第一层生效。Xdebug 3 不再依赖 cookie 或 GET 参数自动传播，得手动转发。
- Laravel 场景：在 HTTP client（如
GuzzleHttp\Client）调用下游前，显式注入X-Forwarded-For和X-Debug头（虽然名字随意，但要保持一致） - ThinkPHP 或原生 cURL：确保
curl_setopt($ch, CURLOPT_HTTPHEADER, [...])包含X-Debug: 1或类似标识 - 所有服务的
xdebug.mode必须设为debug，且xdebug.start_with_request推荐设为trigger，再配合xdebug.trigger_value统一用一个值（如PHPSTORM），避免全量开启损耗性能 - 不要依赖浏览器插件触发——它只影响首层请求；微服务间调用必须靠代码透传
Services 面板必须启用日志聚合和分组
不打开 Services 面板的日志聚合，你就得切 5 个终端窗口分别看 user、order、payment、notify、gateway 的输出，漏掉一行日志可能就错过关键错误。
立即学习“PHP免费学习笔记（深入）”；
- 确保每个服务的运行配置都设置了唯一的
Name，比如user-service (8001)、order-service (8002) - Services 面板默认按配置类型分组（如 “PHP”），右键分组名 →
Rename Group改成Microservices更直观 - 勾选每个服务配置里的
Show console when startup finishes，否则启动后日志窗口不会自动弹出 - 日志中出现
Connection refused或Failed to connect to 127.0.0.1 port 9003，说明某个服务的 Xdebug 尝试连本地监听器失败——检查它是否运行在 Docker 内，client_host是否填了宿主机真实 IP（如192.168.1.105）而非localhost
路径映射失效是 Windows + Docker 最常见断点失败原因
Windows 主机上跑 Docker，容器内 PHP 报错路径是 /var/www/user-service/app/Http/Controllers/UserController.php，而 PhpStorm 本地路径是 E:\projects\monorepo\user-service\app\Http\Controllers\UserController.php——如果不做映射，断点永远不命中。
- 进
Settings → Languages & Frameworks → PHP → Servers，添加或编辑对应服务的服务器配置 - 在
Path mappings表格中，左侧填容器内绝对路径（如/var/www/user-service），右侧填本地对应路径（如E:\projects\monorepo\user-service） - 务必使用正斜杠
/，别用 Windows 默认的反斜杠\；路径末尾不要加斜杠，否则映射失败 - 验证方式：在容器内执行
php -i | grep "xdebug.file_link_format"，确认输出里有正确路径格式；再在 PhpStorm 的Debug工具窗口里看 “Frames” 标签页，展开堆栈，鼠标悬停文件名，看提示路径是否匹配本地文件
真正卡住人的从来不是“怎么加断点”，而是服务间网络通不通、Xdebug 上下文传没传、路径映射对不对这三处——它们不出问题时一切丝滑，出一点就全线阻塞，且错误表现常常是“断点灰色不可用”或“Debugger disconnected”，而不是明确报错。
