用途
Docker Compose Watch 模式（2025 正式版）用于本地开发过程中的自动热重载。它通过即时同步文件变更，避免手动重启容器，从而提升开发迭代效率。
主要能力：三种监听动作
-
sync - 热重载 适用于自带热重载能力的框架（如 React、Next.js、Node.js、Flask）。将发生变更的文件直接复制进正在运行的容器中。
-
rebuild - 编译 适用于编译型语言（如 Go、Rust、Java）或依赖发生变更的场景。当文件变化时重建镜像并重新创建容器。
-
sync+restart - 配置变更 适用于需要重启才能生效的配置文件。同步文件并重启容器。
使用方式：核心流程
- 在添加 watch 规则之前，先确认应用已经可以通过
docker compose up正常启动。 - 当运行时本身已经能重载文件时，源码目录优先使用 sync。
- 依赖清单、Dockerfile、编译产物或基础镜像变更时使用 rebuild。
- 仅在进程启动时读取的配置文件使用 sync+restart。
- 为依赖文件夹、构建输出、版本控制目录、缓存、密钥和生成文件添加精确的忽略规则。
- 运行
docker compose up --watch，并同时验证快速源码编辑和依赖变更两种情况。
配置示例
services:
frontend:
build: ./frontend
develop:
watch:
- action: sync
path: ./frontend/src
target: /app/src
ignore: [node_modules/, .git/, dist/]
- action: rebuild
path: ./frontend/package.json
启动命令：docker compose up --watch。
适用场景
- 使用自带热重载框架的前端或后端项目，希望文件变更即时生效。
- 使用编译型语言，需要在源码或依赖变化时自动重建镜像。
- 需要修改仅在启动时读取的配置文件，并自动重启容器。
限制与注意事项
- 需先确保应用能通过
docker compose up正常启动，再添加 watch 规则。 - 忽略规则需精确设置，否则可能同步依赖目录、构建输出等不必要内容。
- 热重载不生效时，需确认容器内应用自身已启用文件监听。
- 容器重启过于频繁时，应将源码同步与清单重建规则拆分。
- 出现文件属主问题时，依赖目录建议使用命名卷，仅同步应用代码。
- 同步缓慢时，应缩小监听路径并排除构建输出或大型生成目录。
故障排查清单
- 未检测到变更：确认监听路径相对于 Compose 文件，且未被 ignore 排除。
- 热重载未触发：确认容器内应用已启用自身的文件监听。
- 容器重启过于频繁：将源码同步与清单重建规则拆分。
- 文件属主问题：依赖目录优先使用命名卷，仅同步应用代码。
- 同步缓慢：缩小监听路径，排除构建输出或大型生成目录。
参考
可使用 docker compose watch --help 和 Docker 的 Compose Watch 文档了解当前的动作集合与 CLI 参数。当 watch 规则涉及服务依赖、profiles、网络或卷时，可搭配 compose-patterns-2025 使用。
优势
- 性能优于大范围 bind mount。
- 减少宿主机与容器之间的文件权限问题。
- 具备重建能力的智能同步。
- 可在受支持的 Docker Desktop 和 Compose 平台上运行。