必须用docker-compose.yml配置PHP解释器，因PhpStorm只识别其定义的服务；手动docker run容器无法被发现，导致断点失效、路径映射错位、composer报错；需确保Docker CLI可达、选Docker Compose模式、服务名匹配、挂载路径一致、Xdebug client_host设为host.docker.internal且端口9003对齐。
直接用 docker-compose.yml 配置 PHP 解释器，别用 docker run 启的容器——PhpStorm 的 Docker 集成只认 docker-compose.yml 里定义的服务，手动启的容器 IDE 根本发现不了，断点不生效、路径映射错位、composer install 报错，八成是这一步错了。
为什么 PhpStorm 找不到你的 Docker 容器？
不是插件没开，而是 PhpStorm 没拿到 docker 命令或守护进程连接不上。常见现象：Settings → PHP → Interpreter → Add… 里 Docker 选项置灰、Services 工具窗口中 Docker 节点灰色断开、报错 Cannot connect to the Docker daemon。
- 终端执行
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） - Linux 用户需确认当前用户在
docker用户组：sudo usermod -aG docker $USER，然后重新登录终端或重启 PhpStorm
PHP 解释器必须选「Docker Compose」模式
哪怕你只跑一个 PHP 容器，只要用了 docker-compose.yml，就必须选「Remote Interpreter → Docker Compose」，不能选「Docker」（单容器模式）。选错会导致容器起不来、挂载路径失效、php -v 验证失败。
-
docker-compose.yml必须放在项目根目录，且文件名是docker-compose.yml（不是.yaml） - 服务名必须是
services:下一级 key，比如services: app:，配置时就选app，区分大小写，不能填容器名或镜像名 - 解释器路径固定填
/usr/bin/php，别写/bin/sh -c "php"或其他变体 - 如果提示
Connection refused，先终端执行docker-compose up -d app确保服务已启动，再点 PhpStorm 里的Test Connection
路径映射错位导致代码不生效？
本地改了代码，容器里没反应，或者 composer install 装到容器里却找不到 vendor，基本是卷映射（volumes）没对齐。
立即学习“PHP免费学习笔记（深入）”；
-
docker-compose.yml中的volumes必须把项目根目录挂载到容器内对应路径，例如./:/var/www/html；这个/var/www/html要和 PhpStorm 配置解释器时的Project root path（默认值）一致 - 不要在
docker-compose.yml里同时写build:+Dockerfile并开启 PhpStorm 的「Build image before run」——容易重复构建；更稳的做法是先手动docker compose build，再让 PhpStorm 直接运行镜像 - YAML 缩进必须用空格，不能用 tab；服务名不能含下划线以外的特殊字符（如
my-app可以，my.app会解析失败）
Xdebug 断点不触发？三处必须严格对齐
断点变空心圆、控制台没 [Step Debug] 日志，说明容器内 Xdebug 没连上 PhpStorm，不是 IDE 设置问题，而是客户端（容器）和服务端（IDE）通信链路断了。
- 容器内
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 - PhpStorm 中 Debug port 必须设为
9003（Xdebug 3 默认），且Settings → PHP → Servers里路径映射要和volumes一致（例如/var/www/html→ 项目根目录） - 开发时务必禁用
opcache，并确保开启「Start listening for PHP debug connections」
最容易被忽略的是：docker-compose.yml 里 PHP 服务必须显式暴露 9003 端口（哪怕只是内部通信），否则容器网络策略可能拦截 Xdebug 连接请求。
