PhpStorm的Docker集成必须使用docker-compose.yml定义PHP服务，选“Docker Compose”模式而非单容器模式，确保服务名、路径映射、Xdebug配置（xdebug.mode=debug、client_host=host.docker.internal、PhpStorm监听9003端口）三者严格一致。
直接用 docker-compose.yml 配置 PHP 解释器，别碰 docker run —— PhpStorm 的 Docker 集成只认 docker-compose 定义的服务，手动 docker run 启的容器 IDE 根本发现不了，断点不生效、路径映射错位、Xdebug 连不上，八成是这一步错了。
PhpStorm 找不到 Docker Desktop？先查 CLI 和启动方式
Settings → PHP → Interpreter → Add → Docker 选项置灰或不出现，不是插件没开，而是 PhpStorm 没拿到 docker 命令。
- 终端执行
docker --version和docker info，必须能正常返回；如果报command not found，说明 CLI 没进PATH：macOS 要在 Docker Desktop 设置里勾选 “Use the Docker command in the terminal”，Windows 安装时得勾选 “Add Docker to PATH” - 别从开始菜单或 Dock 直接点开 PhpStorm —— 它不继承 shell 的环境变量；改用终端启动：
open -a PhpStorm（macOS）、start /d "C:\Program Files\JetBrains\PhpStorm\bin" phpstorm64.exe（Windows） - 确认 Docker Desktop 图标是绿色（macOS）或系统托盘显示运行中（Windows）
PHP 解释器必须走「Docker Compose」模式
选错配置类型，后面全白搭。哪怕你只跑一个 PHP 容器，只要用了 docker-compose.yml，就必须选「Docker Compose」，不能选「Docker」（单容器）。
- File → Settings → PHP → Interpreter → Add → Remote Interpreter → Docker Compose
-
docker-compose.yml路径要填对，且文件里services:下的 PHP 服务名（比如php或app）必须和配置里选的 service name 完全一致（区分大小写） - 解释器路径固定填
/usr/bin/php，别写/bin/sh -c "php"或其他变体 - 如果提示
Connection refused，先终端执行docker-compose up -d php确保服务已启动，再点 PhpStorm 里的 Test Connection
Xdebug 断点不触发？三处必须同步对齐
断点变空心圆、控制台没 Xdebug: [Step Debug] 日志，基本是客户端（容器）和服务端（PhpStorm）通信链路断了，尤其 macOS/Windows 上 host.docker.internal 映射容易出错。
立即学习“PHP免费学习笔记（深入）”；
- 容器内
php.ini必须启用 Xdebug 3：设xdebug.mode=debug，不是旧版的xdebug.remote_enable=1 -
xdebug.client_host不能写localhost（那是容器自己）：Linux/macOS 填host.docker.internal，macOS M1/M2 或新版 Docker Desktop 可能需docker.for.mac.host.internal；Windows 填host.docker.internal - PhpStorm 中：Settings → PHP → Debug → Xdebug → Debug port 设为
9003（Xdebug 3 默认），并勾选 “Start listening for PHP debug connections”；同时 Settings → PHP → Servers 里，Host 填localhost，Port 填你对外暴露的 Nginx/Apache 端口（如8080），Path Mapping 必须把项目根目录映射到容器内路径（如/var/www/html）
最常被跳过的其实是路径映射一致性：docker-compose.yml 的 volumes、PhpStorm 的 Server 配置、Xdebug 的 Path Mapping，三者指向的本地路径和容器路径必须完全一致，差一个点都会导致断点失效。别信“差不多”，IDE 不认模糊匹配。
