Windows 本地 EasySwoole 项目（Docker Desktop 挂载运行+热加载配置）

超详细：Windows 本地 EasySwoole 项目（Docker Desktop 挂载运行+热加载配置）

前言

在使用 EasySwoole 进行项目开发时，为了避免本地环境（Windows）与生产环境（Linux）的差异导致兼容性问题，很多开发者会选择使用 Docker 进行环境隔离。本文将详细讲解如何将本地 E:\phpStudy_64\phpstudy_pro\WWW\my-es-app 目录下的 EasySwoole 项目，通过 Docker Desktop 实现目录挂载运行，同时解决「本地修改代码容器内不更新」「热加载失效」等常见问题，全程保姆级教程，适合新手入门。

一、前置准备

1. 已安装的软件

• Docker Desktop（Windows 版本，建议最新版，需开启 WSL 2 后端，避免挂载问题）
• 本地 EasySwoole 项目（路径：E:\phpStudy_64\phpstudy_pro\WWW\my-easyswoole）
• 初始化 composer74 require easyswoole/easyswoole=^3.4 --ignore-platform-reqs
• 终端工具（Windows 终端、PowerShell、Git Bash 均可，用于执行 Docker 命令）

2. 核心知识点说明

• Docker 挂载：通过 -v 参数（docker run）或 volumes 节点（docker-compose）实现「本地目录」与「容器内目录」的文件同步，本地修改文件会自动同步到容器内（反之亦然）。
• EasySwoole 特性：常驻内存的 Swoole 服务，启动时会将代码加载到内存，即使文件同步到容器，也需要重启/重载服务才能生效（开发环境可开启热加载自动重载）。
• Windows 路径注意：Docker 识别的 Windows 本地路径需转换格式（E:\xxx\yyy → /e/xxx/yyy 或 //e/xxx/yyy）。

二、步骤 1：配置 Docker Desktop 磁盘共享（关键）

Windows 环境下，Docker 无法直接访问本地磁盘，需先开启磁盘共享权限，否则挂载会失效。

1. 打开 Docker Desktop，点击顶部菜单栏「Settings」（设置图标）。
2. 在左侧导航栏选择「Resources」→「File Sharing」。
3. 在共享磁盘列表中，勾选项目所在盘符 E:（确保勾选后无红色警告）。
4. 点击底部「Apply & Restart」，等待 Docker 重启生效（重启过程约 1-2 分钟，请勿关闭）。
5. 验证：重启完成后，Docker 状态栏显示「Docker Desktop running」即表示共享配置成功。

注意：如果勾选磁盘时提示权限不足，需以管理员身份运行 Docker Desktop，同时确保本地磁盘 E: 无加密、无访问限制。

三、步骤 2：选择运行方式（两种方案，推荐方案二）

方案一：使用 docker run 命令直接挂载运行（快速测试）

该方案适合快速验证挂载效果，无需编写配置文件，适合新手入门。

1. 拉取 EasySwoole 官方镜像

选择与项目兼容的 EasySwoole 镜像（推荐 5.x 版本，内置 PHP、Swoole 扩展，无需手动配置环境）：

# 拉取 EasySwoole 5.x 官方镜像
docker pull easyswoole/easyswoole:5.x

2. 执行挂载运行命令

核心参数说明：

• -v：本地目录:容器内目录（路径格式必须转换为 Docker 识别的格式）。
• -p：端口映射（本地 9501 端口 → 容器 9501 端口，EasySwoole 默认端口）。
• --name：容器命名（方便后续操作，此处命名为 my-es-app-container）。
• -d：后台运行容器，不占用终端窗口。

完整命令：

# 注意：本地路径 E:\phpStudy_64\phpstudy_pro\WWW\my-es-app 转换为 /e/phpStudy_64/phpstudy_pro/WWW/my-es-app
docker run -it --rm -p 9501:9501 -v E:/phpStudy_64/phpstudy_pro/WWW/my-es-app:/easyswoole --name my-es-app-dev easyswoole/easyswoole3

3. 验证容器是否运行成功

# 查看正在运行的容器
docker ps

# 若容器未运行，查看日志排查错误
docker logs my-es-app-container

执行成功后，终端会显示容器 ID，且 docker ps 列表中能看到 my-es-app-container，状态为 Up 即表示运行成功。

4. 验证挂载是否生效（核心步骤）

挂载是否成功，不能直接看项目运行效果，需通过「文件同步」验证：

1. 进入容器内部交互式终端：

docker exec -it my-es-app-container /bin/bash

2. 切换到容器内挂载目录，创建测试文件：

# 切换到容器内项目目录
cd /var/www/my-es-app

# 创建测试文件
touch docker-test.txt

3. 回到本地项目路径 E:\phpStudy_64\phpstudy_pro\WWW\my-es-app，查看是否出现 docker-test.txt 文件（若出现，说明挂载同步正常）。
4. 反向验证：本地创建 local-test.txt，回到容器内执行 ls，若能看到该文件，说明挂载双向同步正常。

在宿主机（Windows）PowerShell 或 CMD 中执行（需已安装 PHP + Composer）

cd E:\phpStudy_64\phpstudy_pro\WWW\my-es-app
composer require easyswoole/easyswoole=^3.4
php vendor/bin/easyswoole install

方案二：使用 docker-compose.yml 挂载运行（推荐，易维护）

该方案适合长期开发，配置文件可复用，后续修改端口、挂载目录只需修改配置文件，无需重新输入冗长命令。

1. 本地项目根目录创建 docker-compose.yml

在 E:\phpStudy_64\phpstudy_pro\WWW\my-es-app 下创建 docker-compose.yml 文件（无后缀名），内容如下：

version: '3.8' # 兼容 Docker Desktop 最新版，建议使用 3.8 及以上版本
services:
  my-es-app:
    image: easyswoole/easyswoole:5.x # 拉取的 EasySwoole 镜像
    container_name: my-es-app-container # 容器名称
    ports:
      - "9501:9501" # 端口映射：本地 9501 → 容器 9501
    volumes:
      # 本地目录 → 容器内目录（路径转换：E:\xxx → /e/xxx）
      - /e/phpStudy_64/phpstudy_pro/WWW/my-es-app:/var/www/my-es-app
    working_dir: /var/www/my-es-app # 容器工作目录（默认进入项目根目录）
    restart: always # 容器异常退出时自动重启（可选，提升稳定性）

2. 执行 docker-compose 启动命令

打开本地终端，切换到项目根目录（E:\phpStudy_64\phpstudy_pro\WWW\my-es-app），执行以下命令：

# 后台启动容器（-d 可选，不加则前台运行，终端关闭容器停止）
docker-compose up -d

3. 常用 docker-compose 命令

# 停止容器
docker-compose down

# 查看容器状态
docker-compose ps

# 重启容器
docker-compose restart

# 查看容器日志
docker-compose logs -f

4. 验证挂载生效

与方案一的「验证挂载是否生效」步骤一致，此处不再赘述。

四、步骤 3：容器内启动 EasySwoole 项目

无论使用哪种方案，容器运行后都需要进入容器内部，启动 EasySwoole 服务。

1. 进入容器内部

# 方案一/方案二通用（容器名均为 my-es-app-container）
docker exec -it my-es-app-container /bin/bash

执行成功后，终端提示符变为 sh-4.4# 或 root@xxx:/#，表示已进入容器内部。

2. 验证容器内项目目录

# 切换到项目根目录
cd /var/www/my-es-app

# 查看项目文件（确认本地项目文件已同步）
ls

若能看到 App、vendor、composer.json 等文件，说明挂载同步正常。

3. 安装 Composer 依赖（若项目未安装）

如果本地项目未安装 vendor 依赖包，需在容器内执行 Composer 命令安装（容器内已内置 Composer）：

# 切换阿里云镜像源（加速安装，避免网络超时）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 安装项目依赖
composer install

# 安装热加载依赖（开发环境必备，后续配置热加载使用）
composer require easyswoole/trigger --dev

4. 启动 EasySwoole 服务（开发模式）

EasySwoole 5.x 版本命令与 4.x 不同，核心启动命令如下（必须带 dev 模式，否则热加载无法生效）：

# 停止已有服务（若已启动，避免端口冲突）
php vendor/bin/easyswoole server stop -force

# 以 dev 模式后台启动服务（-d 后台运行，-mode=dev 开发模式）
php vendor/bin/easyswoole server start -d -mode=dev

# 查看服务运行状态
php vendor/bin/easyswoole server status

执行 status 命令后，若显示「运行模式：dev」「服务状态：运行中」，说明项目启动成功。

5. 本地访问项目

打开本地浏览器，访问 http://localhost:9501 或 http://127.0.0.1:9501，若能看到 EasySwoole 欢迎页，说明项目运行成功。

五、步骤 4：解决「本地修改代码，容器内不更新」问题

很多新手会遇到「本地修改代码后，浏览器刷新无变化」的问题，核心原因有两个：挂载同步问题 和EasySwoole 常驻内存机制，我们逐一解决。

问题 1：挂载同步失效（文件未同步到容器）

排查与解决方案：

1. 重新验证 Docker 磁盘共享：确保 E: 盘已勾选，Docker 已重启。
2. 检查路径格式：本地路径是否转换为 /e/xxx/xxx（正斜杠、盘符小写、无冒号）。
3. 避免特殊字符：项目路径中是否包含中文、空格、特殊符号（如 #、@），建议路径仅包含字母、数字、下划线。
4. 手动同步测试：本地修改 App/HttpController/Index.php，容器内执行 cat App/HttpController/Index.php，查看是否能看到修改内容。

问题 2：EasySwoole 常驻内存（文件同步但代码不生效）

解决方案 1：手动平滑重启服务（简单高效）

本地修改代码并保存（确保同步到容器）后，进入容器内执行以下命令，无需停止整个服务，实现无感知更新：

# 容器内项目根目录执行
php vendor/bin/easyswoole server reload

执行后等待 1-2 秒，刷新浏览器即可看到修改效果。

解决方案 2：开启热加载（自动感知文件变更，无需手动重启）

开发环境推荐开启热加载，无需每次修改代码都执行 reload 命令，配置步骤如下：

1. 容器内项目根目录创建 config 文件夹，新建 EasySwoole.php 配置文件：

<?php
// 常量兜底定义，避免框架加载时未定义
defined('EASYSWOOLE_ROOT') or define('EASYSWOOLE_ROOT', dirname(__DIR__));

return [
    'server' => [
        'host' => '0.0.0.0', // 容器内必须绑定 0.0.0.0，外部才能访问
        'port' => 9501,
        'mode' => SWOOLE_PROCESS,
        'sockType' => SWOOLE_SOCK_TCP,
        'options' => [
            'worker_num' => 4,
            'max_request' => 1000,
        ]
    ],
    'hotReload' => [
        'enable' => true, // 开启热加载（仅开发环境开启）
        'monitorDir' => [EASYSWOOLE_ROOT], // 监控项目根目录
        'monitorExt' => ['php', 'ini', 'json'], // 监控的文件后缀
        'ignoreDir' => [
            EASYSWOOLE_ROOT . '/vendor',
            EASYSWOOLE_ROOT . '/runtime'
        ], // 忽略无需监控的目录
        'interval' => 5, // 适配 Windows+Docker 同步延迟，设置 5 秒监控间隔
    ],
    'runtime' => [
        'dir' => EASYSWOOLE_ROOT . '/runtime',
    ],
    'env' => [
        'runMode' => 'dev' // 明确开发模式
    ]
];

2. 重启 EasySwoole 服务（配置修改后需彻底重启才能生效）：

# 容器内执行
php vendor/bin/easyswoole server stop -force
php vendor/bin/easyswoole server start -d -mode=dev

3. 验证热加载：本地修改 Index.php 并保存，等待 5 秒左右，刷新浏览器即可看到修改效果，无需手动执行任何命令。

六、步骤 5：常见问题排查与避坑指南

1. 容器启动失败，日志提示「permission denied」

• 原因：容器内目录权限不足，无法读取挂载的项目文件。
• 解决方案：容器内执行以下命令赋予目录权限：

chmod -R 755 /var/www/my-es-app

2. 热加载配置后仍不生效

• 排查 1：是否以 dev 模式启动服务（必须带 -mode=dev）。
• 排查 2：配置文件路径是否为 config/EasySwoole.php（大小写敏感，文件名首字母大写）。
• 排查 3：查看 runtime/logs/easyswoole.log 日志，是否有「hotReload」相关报错。
• 排查 4：本地编辑器是否开启「自动保存」，建议手动保存文件，强制更新文件修改时间。

3. 浏览器访问 localhost:9501 提示「无法访问」

• 排查 1：容器是否正常运行（docker ps 查看状态）。
• 排查 2：端口是否映射正确（本地 9501 端口是否被占用，可更换为 9502 端口）。
• 排查 3：容器内服务是否正常启动（php vendor/bin/easyswoole server status 查看）。

七、总结

1. Windows 环境下 Docker 挂载的核心是「开启磁盘共享」+「转换路径格式」，这是挂载成功的前提。
2. EasySwoole 项目挂载后，代码不生效的核心是「常驻内存机制」，可通过 reload 手动重启或开启热加载自动更新。
3. 开发环境推荐使用 docker-compose.yml 配置，易维护、可复用，配合热加载大幅提升开发效率。
4. 生产环境不建议开启热加载，可使用 php vendor/bin/easyswoole server reload 实现无感知更新，保证服务稳定性。

通过本文的步骤，你可以轻松实现本地 EasySwoole 项目的 Docker 挂载运行，避免环境差异带来的兼容性问题，同时解决开发过程中的常见痛点，为后续项目部署上线打下坚实基础。