必须用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 验证失败。

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

• 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）没对齐。

• 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 连接请求。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！