必须用docker-compose.yml配置php解释器，phpstorm不识别docker run容器，会导致断点失效、路径映射错位、composer install找不到vendor；需选remote interpreter→docker compose模式，服务名严格匹配services下键名，解释器路径填/usr/bin/php，确保docker-compose.yml在项目根目录且卷挂载路径与ide项目根路径一致。
必须用 docker-compose.yml 配置 PHP 解释器，手动 docker run 启的容器 PhpStorm 根本识别不到——断点不触发、路径映射错位、composer install 装到容器却找不到 vendor，八成是这一步错了。
PhpStorm 找不到 Docker 服务？先确认 CLI 和权限
Settings → PHP → Interpreter → Add… 里 Docker 选项置灰，或 Services 工具窗口中 Docker 节点灰色断开，大概率不是插件没开，而是 IDE 拿不到 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） - 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 却在 IDE 里标红、运行时报 Class not found，基本是 volumes 没对齐。
-
docker-compose.yml中的本地路径（如./:/var/www/html）必须和 PhpStorm 当前打开的项目根路径完全一致 - 不要用绝对路径写死，避免团队协作时路径不一致；尤其注意 macOS/Windows 的路径分隔符差异（IDE 内部会自动转换，但写错仍会失效）
- 如果用了多级子目录作为工作区（比如项目实际在
project/backend），那docker-compose.yml也得放在backend目录下，而不是父级
Xdebug 断点不生效？重点核对 client_host 和端口
容器里 Xdebug 日志显示已连接，但 PhpStorm 不停，问题几乎全出在网络可达性上，尤其是 host.docker.internal 在不同系统的行为差异。
- Linux 和 Windows：设
XDEBUG_CLIENT_HOST=host.docker.internal，且extra_hosts加上- "host.docker.internal:host-gateway" - macOS：用
XDEBUG_CLIENT_HOST=docker.for.mac.host.internal（旧版 Docker Desktop）或host.docker.internal（新版），不加extra_hosts - PhpStorm Debug port 必须和容器内
XDEBUG_CLIENT_PORT（默认9003）一致，且「Start Listening for PHP Debug Connections」要开启 - 别漏掉
XDEBUG_MODE=debug，Xdebug 3+ 默认不启用调试模式
最容易被忽略的是：docker-compose.yml 里服务定义是否包含 ports 段（哪怕只是 - "9003:9003"），以及 PhpStorm 的 Servers 配置里路径映射是否和卷挂载路径严格匹配——IDE 不会自动推导，填错一个字符就无法解析断点位置。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
