PhpStorm 识别不到 Docker Desktop 的主因是环境变量未继承或 Docker CLI 路径缺失，需确保 Docker Desktop 运行、CLI 可执行，并通过终端启动 PhpStorm；配置时须按项目类型选对 Docker Compose 或单容器模式，正确设置服务名、挂载路径、Xdebug 参数及用户 UID。
PhpStorm 识别不到 Docker Desktop（Windows/macOS）
常见现象是 Settings > PHP > Interpreter 里点“Add…”后，Docker 选项置灰或根本没出现。不是插件没装，而是 PhpStorm 没拿到 Docker CLI 的执行权限或路径。
- 先确认 Docker Desktop 已启动且状态栏图标是绿色（macOS）或系统托盘有运行图标（Windows）
- 在终端执行
docker --version和docker info，确保能正常返回——如果报 “command not found”，说明 CLI 未加入 PATH；macOS 需检查是否勾选了 Docker Desktop 设置里的Use the Docker command in the terminal；Windows 用户要确认安装时勾选了Add Docker to PATH - PhpStorm 启动方式影响环境变量：直接从开始菜单或 Dock 启动，可能不继承 shell 的 PATH；推荐用终端执行
jetbrains-toolbox或open -a PhpStorm（macOS）、start /d "C:\Program Files\JetBrains\PhpStorm\bin" phpstorm64.exe（Windows）来启动，确保环境变量完整
配置 PHP 解释器时选错 Docker 配置类型
PhpStorm 提供两种 Docker 解释器：「Docker Compose」和「Docker」（即单容器）。选错会导致容器起不来、路径挂载失败或 composer install 报错。
- 如果你的项目根目录下有
docker-compose.yml，且 PHP 服务定义明确（如 service 名为app），就选Docker Compose；别手快选成单容器模式 - 选
Docker Compose后，必须指定docker-compose.yml路径和 service name——这个 service name 必须和 yml 文件里一级 key 完全一致（区分大小写），比如写成APP而不是app就会连接失败 - 单容器模式适合快速验证，但需手动填镜像名（如
php:8.2-cli）、工作目录（/var/www/html）、端口映射等，容易漏掉volumes挂载，导致代码修改不生效
容器内 PHP 扩展缺失导致 Xdebug 断点不触发
本地 PHP 环境装了 xdebug，但 Docker 容器里没配，PhpStorm 就收不到调试连接请求，断点变空心圆，控制台也无 Xdebug: [Step Debug] Could not connect 日志。
- 不要在宿主机装 xdebug，而要在 Docker 镜像中启用：PHP-FPM 镜像需额外安装
php-xdebug包，并在php.ini里显式开启（zend_extension=xdebug.so） - Xdebug 3 配置项和旧版不同：必须设
xdebug.mode=debug，且xdebug.client_host在 Docker 场景下不能写localhost（那是容器自己的 loopback）；Linux/macOS 用host.docker.internal，Windows Docker Desktop 也支持该 DNS；若用 WSL2，可能需要手动加--add-host=host.docker.internal:host-gateway - PhpStorm 的
Settings > PHP > Servers中，Host 必须和xdebug.client_host一致，Port 默认是9003（Xdebug 3），不是旧版的9000
挂载路径同步失败或文件权限报错
代码改了，容器里看不到；或者 composer install 提示 Permission denied，本质是 volume 挂载路径或用户 UID 不匹配。
立即学习“PHP免费学习笔记（深入）”；
- Docker Compose 的
volumes必须用绝对路径，相对路径（如./src:/var/www/html）在 PhpStorm 启动时可能解析错误；建议统一用${PWD}/src:/var/www/html（Linux/macOS）或%cd%/src:C:/www/html（Windows） - PHP 容器默认以
www-data（UID 33）运行，但宿主机文件属主可能是 UID 1000；在docker-compose.yml的 service 下加user: "1000:1000"强制对齐，否则composer写缓存会失败 - macOS 上启用了 gRPC FUSE（Docker Desktop 4.19+ 默认开启），可能导致某些 IDE 文件监听失效；临时关闭它（Settings > General > Use the new Virtualization framework）可缓解，但会影响性能
