phpstorm在Debian上如何使用Docker

在 Debian 上配置 PhpStorm 使用 Docker

一 环境准备

• 安装 Docker 与 Docker Compose（Debian 12 示例）
  • 更新索引并安装依赖：
    • sudo apt update & & sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  • 添加 Docker 官方 GPG 密钥与软件源：
    • sudo install -m 0755 -d /etc/apt/keyrings
    • curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
    • echo “deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  • 安装并启动服务：
    • sudo apt update & & sudo apt install -y docker-ce docker-ce-cli containerd.io
    • sudo systemctl start docker & & sudo systemctl enable docker
  • 验证安装：
    • docker version
    • docker info
  • 可选：安装 Compose 插件（便于使用 docker compose 命令）
    • sudo apt install -y docker-compose-plugin
• 将当前用户加入 docker 组（避免每次 sudo）
  • sudo usermod -aG docker $USER（需重新登录或重启会话生效）
• 网络与镜像加速（可选，提升拉取速度）
  • 编辑 /etc/docker/daemon.json（不存在则新建）：
    • { “registry-mirrors”: [“https://< 你的镜像加速地址> ”] }
  • 重启 Docker：sudo systemctl restart docker 以上步骤适用于 Debian 12，命令在 Debian 11 上也通用（源地址中的代号可能需要调整）。

二 在 PhpStorm 中连接 Docker

• 打开设置：File -> Settings -> Build, Execution, Deployment -> Docker（macOS 为 Preferences）
• 新增 Docker 连接：点击 +，选择 Docker
  • 推荐使用本机 Unix Socket：选择 Docker for Linux（自动使用 /var/run/docker.sock）
  • 如需 TCP 方式（仅在本机或受信网络中）：选择 TCP Socket，Engine API URL 填 tcp://localhost:2375（需确保 Docker 守护进程监听该端口，生产环境不建议开启 TLS 外的 2375）
• 测试连接成功后应用设置 上述 UI 路径与连接方式适用于 PhpStorm 的 Docker 集成。

三 配置 PHP 远程解释器与运行调试

• 配置 CLI 解释器
  • Settings -> Languages & Frameworks -> PHP -> CLI Interpreter -> + -> From Docker, Vagrant, VM, WSL, Remote…
  • 选择上一步添加的 Docker 连接，指定服务与 PHP 可执行路径（常见为 php 或 php-fpm 容器内路径）
• 配置运行/调试
  • Run/Debug Configurations -> + -> PHP Remote Debug
  • Server：新建或选择已有 Server，Host 填项目域名或 localhost，端口为 Web 服务端口（如 80/443/8080），Debugger 选 Xdebug
  • 设置断点后启动调试，PhpStorm 将通过 Xdebug 与容器内的 PHP 建立调试会话
• 路径映射要点
  • 在解释器或运行配置中设置本地项目路径与容器内项目路径的 Path Mappings，确保断点命中和源码同步 以上步骤覆盖 PhpStorm 的远程解释器与 Xdebug 调试配置要点。

四 使用 Docker Compose 一键编排

• 示例 docker-compose.yml（PHP-FPM + Nginx，开发常用）
  • version: “3.8” services: app: build: . volumes: - .:/var/www/html:cached - ./php.ini:/usr/local/etc/php/conf.d/php.ini:ro environment: - XDEBUG_MODE=debug - XDEBUG_CLIENT_HOST=host.docker.internal - XDEBUG_CLIENT_PORT=9003 web: image: nginx:alpine ports: - “8080:80” volumes: - .:/var/www/html:cached - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro depends_on: - app
• 在 PhpStorm 中使用
  • Settings -> PHP -> Docker：添加 Docker Compose 配置，指向上述 compose 文件与服务
  • CLI 解释器选择 Compose 服务（如 app）
  • Run/Debug Configurations 选择 Server 与对应服务，启动调试 该编排示例展示了将应用代码挂载到容器内、通过 Nginx 暴露端口，以及便于 PhpStorm 调试的常见做法。

五 常见问题与排查

• Cannot connect to the Docker daemon
  • 检查 Docker 服务：sudo systemctl status docker；未运行则 sudo systemctl start docker
  • 权限问题：将用户加入 docker 组并重新登录；或临时使用 sudo 运行 PhpStorm（不推荐）
• Xdebug 无法连接
  • 确认容器内 PHP 安装了 Xdebug，并与 PhpStorm 的 Debug 端口一致（常见为 9003；老版本 Xdebug 2 使用 9000，注意与 CLI/FPM 的监听端口区分）
  • 在 PhpStorm：Settings -> PHP -> Debug 设置 Xdebug Port；Settings -> PHP -> DBGp Proxy 配置 IDE Key、Host、Port；Settings -> PHP -> Servers 配置域名与路径映射
  • 浏览器发起请求时携带 XDEBUG_SESSION_START=PHPSTORM（或使用书签/扩展触发）
• 路径断点不匹配
  • 在解释器或运行配置中校正 Path Mappings（本地路径 < -> 容器内路径）
• 2375 端口安全
  • 仅在受信网络或本机使用 TCP 2375；生产环境建议启用 TLS 或仅用 Unix Socket 以上为常见故障的定位与修复思路，涉及服务状态、权限、端口与路径映射等关键检查点。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！