PhpStorm的Docker集成必须使用docker-compose.yml配置，选“Docker Compose”模式，确保服务名、路径映射、Xdebug配置三者严格一致；手动docker run启动的容器IDE无法识别，导致断点失效、路径错位、Xdebug连不上。
直接用 docker-compose.yml 启动，别手动 docker run —— PhpStorm 的 Run Configuration 只识别 docker-compose.yml 里定义的服务，手启的容器 IDE 完全看不见，服务连不上、日志刷不出来、端口映射也错位。
Run Configuration 必须选 Docker Compose 类型
PhpStorm 的“运行配置”里没有“Docker”或“Container”选项，只有 Docker-Compose。点 Run → Edit Configurations → + → Docker-Compose 才是正路。
- 填错类型（比如误选成
Docker或PHP Script）会导致配置保存但执行时静默失败，控制台无输出 -
docker-compose.yml文件路径必须指向项目根目录下的真实文件，不能是相对路径别名或链接 - Service name 下拉菜单里列出的项，必须和
docker-compose.yml中services:下一级 key 完全一致（大小写敏感），例如写成APP而 yml 里是app就会报Service not found - 如果下拉为空，先检查 yml 缩进是否全为空格（tab 会被忽略）、文件后缀是不是
.yml（不是.yaml）
卷映射（volumes）必须与 PhpStorm 项目路径对齐
PhpStorm 不会自动猜你代码在哪，它只按 volumes 字段挂载。挂错路径，composer install 装到容器里、本地看不到；断点打在 /var/www/html/index.php，但你实际编辑的是 /Users/xxx/project/index.php，那就永远不触发。
- 典型正确写法：
./:/var/www/html（.是项目根目录，/var/www/html是容器内 Web 根目录） - 如果项目结构是
src/在子目录，就得写成./src:/var/www/html，否则路径映射断裂 - Windows 用户注意反斜杠问题：不要写
C:\project\:/var/www/html，应统一用正斜杠C:/project/:/var/www/html或使用${PWD}变量 - Mac/Linux 用户若用
~开头路径（如~/project:/var/www/html），PhpStorm 无法解析，必须展开为绝对路径
启动前务必确认服务已就绪，别依赖 PhpStorm 自动等待
PhpStorm 的 Start services before launch 选项只是发个 docker-compose up -d <service>，不校验容器是否真正 ready。常见现象：Nginx 报 502、PHP-FPM 拒绝连接、MySQL 连不上 —— 其实是 PHP 容器还没加载完扩展，或者 DB 容器还在初始化。
立即学习“PHP免费学习笔记（深入）”；
- 勾选
Start services before launch后，建议同步设置Wait for services to be ready并调高超时时间（至少60秒） - 更可靠的做法：先终端执行
docker-compose up -d php nginx db，再用docker-compose logs -f php确认 PHP-FPM 已监听、Xdebug 已加载、php -m | grep xdebug有输出 - 如果服务反复重启，看
docker-compose ps状态列是否为Restarting，大概率是环境变量缺失、配置文件路径错误或依赖服务（如 DB）未就绪
Xdebug 连接失败？先盯住 client_host 和端口一致性
断点变空心圆、控制台没 [Step Debug] 日志，90% 是容器连不到宿主机的 PhpStorm 监听端口，而不是 Xdebug 没装。
- 容器内
xdebug.client_host必须设为host.docker.internal（Windows/macOS Docker Desktop），Linux 需改用172.17.0.1或宿主机真实 IP - macOS Sonoma+ 用户若启用新虚拟化框架，
host.docker.internal可能失效，临时方案是改用docker.for.mac.host.internal - PhpStorm 必须开启
Start listening for PHP debug connections（右上角电话图标亮起），且 Debug port 固定为9003（Xdebug 3 默认） - 检查
docker-compose.yml是否暴露了9003端口：ports: ["9003:9003"]—— 即使只用于内部通信，这行也不能省
最易被忽略的一点：PhpStorm 的 Services 工具窗口里看到的容器列表，是实时从 docker-compose.yml 解析出来的，不是 Docker daemon 的全局视图。删掉 yml 里某个 service，即使容器还在跑，PhpStorm 也会立刻“失联”——所以别靠容器是否 running 来判断配置是否生效，得看 yml 结构和 PhpStorm 内部解析结果是否匹配。
