phpstorm在Debian上如何使用Docker

在 Debian 上配置 PhpStorm 使用 Docker

一 环境准备

万事开头先搭台。想在 Debian 上顺畅地玩转 PhpStorm 和 Docker，第一步就是把基础环境给搭建扎实了。下面以 Debian 12 为例，带你走一遍标准流程。

安装 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

源添加好了，就可以正式安装 Docker 引擎并启动服务了：

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，如果能看到版本和服务信息，说明 Docker 已经成功跑起来了。

为了后续使用更方便，建议安装 Docker Compose 插件。这样就能直接使用 docker compose 命令了：

sudo apt install -y docker-compose-plugin

将当前用户加入 docker 组（避免每次 sudo）

每次执行 Docker 命令都要加 sudo 太麻烦了。一个常见的做法是把你的用户加入 docker 组：

sudo usermod -aG docker $USER

注意，执行这个命令后，你需要重新登录系统或者重启当前会话，这个权限变更才会生效。

网络与镜像加速（可选，提升拉取速度）

如果你在国内，可能会觉得从 Docker Hub 拉取镜像速度不够理想。这时候可以配置一个镜像翻跟斗。编辑（或新建）/etc/docker/daemon.json 文件：

{“registry-mirrors”: [“https://<你的镜像加速地址>”]}

保存后，重启 Docker 服务使配置生效：sudo systemctl restart docker。

以上步骤主要针对 Debian 12，但其中的命令在 Debian 11 上基本也通用。唯一可能需要留意的是，软件源地址中的系统代号（$(lsb_release -cs)）会根据你的系统版本自动适配。

二 在 PhpStorm 中连接 Docker

基础环境搞定，现在该请出主角 PhpStorm 了。我们的目标是把 Docker 引擎“介绍”给 PhpStorm 认识。

打开 PhpStorm，进入设置：File -> Settings -> Build, Execution, Deployment -> Docker（在 macOS 上是 Preferences）。

在这里，点击左上角的 + 号，选择 Docker 来新增一个连接。

连接方式怎么选？对于大多数本地开发场景，推荐使用本机的 Unix Socket。直接选择 “Docker for Linux”，它会自动使用 /var/run/docker.sock 这个默认路径，最省事。

当然，如果你有特殊需求，比如需要通过 TCP 连接（仅限于本机或高度信任的内部网络），可以选择 “TCP Socket”，并在 Engine API URL 里填写 tcp://localhost:2375。这里必须提醒一下：务必确保 Docker 守护进程监听了这个端口，并且生产环境强烈不建议开启没有 TLS 加密的 2375 端口，这会带来安全风险。

配置好后，点击 “Test Connection” 测试一下。看到成功的提示，就可以应用设置了。这个界面路径和连接方式是 PhpStorm 集成 Docker 功能的通用标准。

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

连接建立只是第一步，真正的威力在于让 PhpStorm 能使用容器里的 PHP 环境来运行和调试代码。

配置 CLI 解释器

进入 Settings -> Languages & Frameworks -> PHP -> CLI Interpreter。点击右边的 + 号，选择 From Docker, Vagrant, VM, WSL, Remote…。

在弹出的窗口中，选择你上一步刚刚添加好的 Docker 连接。然后，你需要指定具体的服务（如果你用了 Docker Compose）以及容器内 PHP 可执行文件的路径（通常是 /usr/local/bin/php 或 /usr/bin/php）。

配置运行/调试

接下来配置远程调试。点击 PhpStorm 顶部菜单栏的 Run -> Edit Configurations…，点击 + 号，添加一个 PHP Remote Debug 配置。

在这里，你需要新建或选择一个已有的 Server。关键信息包括：Host（填你的项目域名，本地开发常用 localhost）、Port（Web 服务端口，比如 80、443 或 8080），Debugger 选择 Xdebug。

配置完成后，在代码里设置好断点，然后启动这个调试配置。PhpStorm 就会开始监听，一旦有请求触发，它就能通过 Xdebug 协议与容器内的 PHP 进程建立调试会话，实现单步调试、变量查看等功能。

路径映射要点

这里有个必须注意的细节：路径映射（Path Mappings）。因为你的代码在本地硬盘上，而 PHP 解释器运行在容器里，两者看到的文件路径完全不同。

你必须在解释器配置或运行配置中，明确设置本地项目路径与容器内项目路径的对应关系。比如，本地 /home/user/project 对应容器内的 /var/www/html。只有映射正确，断点才能被准确命中，调试才不会乱套。以上步骤涵盖了在 PhpStorm 中配置远程解释器与 Xdebug 调试的核心要点。

四 使用 Docker Compose 一键编排

对于稍微复杂点的项目，只跑一个 PHP 容器往往不够，通常还需要 Nginx、数据库等。这时候，Docker Compose 就能大显身手了，它能帮你一键启动和管理多个关联的容器。

示例 docker-compose.yml（PHP-FPM + Nginx，开发常用）

下面是一个典型的开发环境编排示例，包含了 PHP-FPM 应用服务和 Nginx Web 服务器：

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 中使用

编写好 docker-compose.yml 后，回到 PhpStorm 的设置：Settings -> PHP -> Docker。在这里添加 Docker Compose 配置，指向你刚刚编写的 compose 文件，并选择对应的服务（比如 app）。

接着，在配置 CLI 解释器时，就可以直接选择这个 Compose 服务了。同样地，在运行/调试配置中，选择对应的 Server 和服务，就能启动调试。

这个编排示例展示了开发中的常见做法：将应用代码以卷（volume）的形式挂载到容器内实现代码同步；通过 Nginx 将服务暴露到主机端口；以及预先配置好 Xdebug 环境变量，方便 PhpStorm 进行调试。

五 常见问题与排查

配置过程很少一帆风顺，遇到问题别慌。下面梳理了几个最常见的“坑”及其解决办法。

Cannot connect to the Docker daemon

这是最常碰到的问题之一。首先，检查 Docker 服务是否在运行：sudo systemctl status docker。如果没运行，用 sudo systemctl start docker 启动它。

如果服务是好的，那多半是权限问题。确认你是否已将用户加入了 docker 组，并且已经重新登录了会话。当然，你也可以临时用 sudo 权限启动 PhpStorm 来测试，但这绝非长久之计。

Xdebug 无法连接

调试连不上，让人头疼。请按以下顺序排查：

1. 确认容器内安装了 Xdebug 扩展，并且版本与 PhpStorm 兼容。目前主流是 Xdebug 3，其默认调试端口是 9003（老旧的 Xdebug 2 使用 9000，注意不要和 PHP-FPM 的端口冲突）。
2. 检查 PhpStorm 的配置：在 Settings -> PHP -> Debug 里确认 Xdebug Port 设置正确；在 Settings -> PHP -> DBGp Proxy 中配置好 IDE Key、Host 和 Port；最后在 Settings -> PHP -> Servers 里核对域名和路径映射。
3. 触发调试会话：在浏览器访问时，通过 URL 参数（如 ?XDEBUG_SESSION_START=PHPSTORM）或使用浏览器调试插件/书签来主动触发调试。

路径断点不匹配

代码停了，但断点位置不对，或者根本不停。这几乎可以肯定是路径映射（Path Mappings）没设对。请返回解释器配置或运行配置的服务器设置中，仔细校正本地路径与容器内路径的映射关系，确保两者指向的是同一份源代码。

2375 端口安全

最后再强调一次安全。如果你因为某些原因配置了 TCP 连接（使用 2375 端口），请务必确保它仅用于本机或绝对可信的内部网络。在生产环境或任何有暴露风险的网络中，强烈建议启用 TLS 加密，或者干脆只使用更安全的 Unix Socket 方式。以上排查思路覆盖了服务状态、用户权限、网络端口和路径映射这几个最关键的问题点。