挂载后代码不生效需同时满足路径写法和卷共享：-v 路径用正斜杠、宿主机目录已加入 docker desktop 文件共享列表、-w 工作目录与挂载目标一致；同步延迟高需加 :cached 参数；顽固卡顿应切换至 wsl2；swoole 未加载需验证镜像含 -swoole 后缀及扩展启用状态。
挂载后代码不生效：路径写法和卷共享必须同时到位
Windows 下用 Docker Desktop 运行 Hyperf，docker run -v 挂载后改代码没反应，不是 watcher 问题，而是挂载根本没成功。常见现象是容器里 /var/www/html 是空的，或只有一层 skeleton 目录结构。
关键点有三个：
-
-v路径中的反斜杠\必须全换成正斜杠/，例如E:/my-hyperf-app，否则 Docker 会静默忽略挂载 - 宿主机路径必须真实存在，且已加入 Docker Desktop 的「文件共享」列表（Settings → Resources → File Sharing）
-
-w工作目录必须显式指定，且与-v中的目标路径一致，否则php bin/hyperf.php start找不到入口文件
文件同步延迟高：别信默认配置，要加 :cached
即使挂载成功，macOS 或 Windows + Docker Desktop 组合下，watcher 响应慢、热重载卡顿，本质是 osxfs 或 file sharing 层的 I/O 同步机制拖慢了 inotify 事件上报。
解决办法不是调 scan_interval，而是改挂载参数：
- 在
-v后追加:cached，例如-v E:/my-hyperf-app:/var/www/html:cached - 该标志告诉 Docker Desktop 使用异步缓存策略，大幅降低文件变更到容器内事件触发的延迟
- 注意：
:delegated在 Windows 上支持不稳定，:cached是更安全的选择
根本性卡顿/监听失效：直接切 WSL2，别硬扛 Docker Desktop
当 :cached 仍无法缓解 watcher 卡顿、FswatchDriver 静默无响应、或 inotify 报 too many open files，说明你已踩进 Docker Desktop 文件系统桥接的深坑。
此时继续调参意义不大，应该切换底层环境：
- 停用 Docker Desktop，启用 WSL2（确认
wsl --status显示默认版本为 2） - 在 WSL2 中安装 PHP 8.1+、Swoole 5.0+，项目代码放在
/home/xxx/my-hyperf这类原生 Linux 路径下 - 禁用 Windows 路径挂载：不要把 Windows 盘（如
/mnt/c/project）当项目根目录，否则FswatchDriver会退化为轮询，且 latency 不可控
镜像里 Swoole 没加载：先验证再启动，别等报错才查
挂载没问题，但容器一启动就报 Class 'Swoole\Http\Server' not found，大概率是镜像没带 Swoole 扩展，而非路径或权限问题。
快速验证三步：
- 运行容器时加
--entrypoint sh，进容器后执行php -m | grep swoole—— 无输出即未加载 - 检查镜像标签是否含
-swoole后缀，例如hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6；不含的镜像（如hyperf/hyperf:8.2-alpine）只是纯 PHP 环境 - 确认
php --ri swoole有输出，且状态为enabled；若提示Extension 'swoole' does not exist，说明扩展文件缺失或extension=swoole.so未写入生效的 php.ini
真正麻烦的不是挂载失败，而是挂载成功了、Swoole 也加载了、watcher 却因为 Windows 文件系统语义差异，在某些场景下漏报事件——这种问题不会抛错，只会让你反复怀疑代码逻辑。这时候得靠 strace -e trace=inotify_add_watch 进容器抓底层调用，而不是改配置文件。
