在 CentOS 上让 PhpStorm 使用 Docker 的完整步骤
一 环境准备
- 安装并启动 Docker（以 CentOS 7/8 为例）：
- 安装依赖与仓库：
- sudo yum -y update
- sudo yum remove -y docker* containerd.io
- sudo yum install -y yum-utils device-mapper-persistent-data lvm2
- sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
- 安装与启动：
- sudo yum install -y docker-ce docker-ce-cli containerd.io
- sudo systemctl start docker && sudo systemctl enable docker
- 验证：
- docker --version
- docker ps -a
- 安装并启动 PhpStorm（Linux 版），首次启动后在设置中确认已启用 Docker 插件（通常默认启用）。
二 在 PhpStorm 中连接 Docker
- 打开设置：File → Settings → Build, Execution, Deployment → Docker（macOS 为 Preferences）。
- 新增连接：点击 +，选择 Docker，在右侧选择连接方式：
- 本机 Docker：选择 Unix Socket，地址填写 unix:///var/run/docker.sock（推荐，安全且无需开放端口）。
- 远程 Docker（可选）：选择 TCP Socket，填写如 tcp://<宿主机IP>:2375；若远程启用了 TLS，需配置证书目录。
- 测试连接成功后应用设置。
三 配置 PHP 远程解释器与运行容器
- 配置 CLI 解释器：Settings → Languages & Frameworks → PHP → CLI Interpreter → + → From Docker, Vagrant, VM, WSL, Remote… → 选择 Docker。
- 选择镜像（如 php:8.2-cli 或项目自定义镜像），PhpStorm 会自动探测 php 可执行文件路径；如需 Composer/PECL，可在容器内安装或在镜像中预置。
- 使用 Docker Compose（可选）：Settings → PHP → Docker Compose，添加项目根目录下的 docker-compose.yml，指定服务与项目根目录映射，便于一键启停与依赖管理。
- 运行与调试容器：
- 在 PhpStorm 的 Services/Docker 工具窗口查看并管理容器；
- 创建 Run/Debug Configurations，选择容器或服务作为运行目标，结合容器内启动命令（如 php-fpm、artisan serve、symfony server:start 等）进行调试。
四 配置 Xdebug 3 远程调试
- 容器内安装并启用 Xdebug 3（示例为 CLI/CLI-Server 场景，FPM 同理）：
- 安装扩展（以 php:8.2-cli 镜像为例）：
- docker exec -it <容器名> sh -lc “pecl install xdebug && docker-php-ext-enable xdebug”
- 写入 php.ini 或 xdebug.ini（路径可用 php --ini 查看）：
- [xdebug]
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.start_with_request=trigger
- xdebug.client_host=host.docker.internal
- xdebug.client_port=9003
- xdebug.idekey=PHPSTORM
- PhpStorm 调试设置：
- Settings → PHP → Debug：将 Xdebug Port 设为 9003（与 xdebug.client_port 一致）。
- Settings → PHP → Debug → DBGp Proxy：IDE key 填 PHPSTORM，Host 填 127.0.0.1，Port 填 9003。
- Settings → PHP → Servers：新增服务器，Host 填项目访问域名或 localhost，Port 填 80/443，Debugger 选 Xdebug，配置本地项目路径与容器内路径的 Path Mappings。
- 触发调试：
- 在浏览器访问时带上参数 ?XDEBUG_SESSION_START=PHPSTORM，或在 CLI 中设置环境变量 XDEBUG_SESSION=PHPSTORM 后执行脚本；
- 在 PhpStorm 中点击 Debug，命中断点即可联动。
五 常见问题与排查
- 权限问题：如 PhpStorm 无法连接 Docker，确保当前用户在 docker 组，或以 sudo 运行 PhpStorm；Unix socket 权限通常为 root:docker 660。
- 连接方式选择：本机优先使用 unix:///var/run/docker.sock；远程若使用 TCP 2375，务必限定在内网并考虑启用 TLS，避免安全风险。
- 路径映射：务必在解释器与 Server 配置中正确设置 本地路径 ↔ 容器内路径，否则断点无法命中、代码同步异常。
- 端口占用：确认 9003（Xdebug）未被其他进程占用；如被占用，修改 php.ini 与 PhpStorm 的 Debug Port 一致后重启调试。
- Xdebug 版本差异：Xdebug 2 与 3 配置项不同，本文为 Xdebug 3 写法；若使用 2.x，请参考 xdebug.remote_enable、xdebug.remote_port 等旧参数。
