Compose Watch 怎样同步源码变化

如果你在容器里开发前端或服务端，每改一次源码都手动重建镜像，反馈会被构建时间拖慢。Compose Watch 的做法是把本地路径和容器目标路径写进 Compose 配置：普通源码用 sync，依赖文件用 rebuild，配置文件则可以用 sync+restart。这样修改保存后，Compose 会按规则更新正在运行的服务。

官方地址：https://docs.docker.com/compose/how-tos/file-watch/

下面用一个名为 web 的可构建服务说明完整配置。Compose Watch 要求 Docker Compose 2.22.0 或更高版本，并且服务通常要有 build，只写预构建 image 的服务不适合这套源码监视方式。

先把源码变化映射到服务容器

第一步是在 compose.yaml 的服务下添加 develop.watch。path 相对 Compose 项目目录，target 是容器内的接收位置；两者不需要同名，但映射关系必须和镜像中的工作目录一致。

services:
  web:
    build: . # 使用本地 Dockerfile 构建，Watch 才能管理该服务
    command: npm start # 启动开发进程，让同步后的源码有可见效果
    develop:
      watch:
        - action: sync # 源码变化只同步文件，不重新构建镜像
          path: ./web # 监听项目目录下的前端源码
          target: /app/web # 把变化写入容器内的应用目录
          ignore:
            - node_modules/ # 忽略本机依赖目录，避免跨平台文件混入

此时的关键不是把整个项目都挂进去，而是明确“哪一段源码需要同步”。例如依赖目录通常不应从主机复制到容器，因为其中可能包含与主机系统或架构相关的原生模块。

按文件类型选择同步还是重建

我在实际配置时最容易踩的坑，是把所有变化都写成 sync。源码文件可以同步，但新增依赖并不会因为文件被复制进去就自动安装；这类变化应该触发重建。

        - action: rebuild # 依赖清单变化时重建镜像并替换服务容器
          path: package.json # 安装依赖需要重新执行镜像构建步骤
        - action: sync+restart # 配置文件同步后重启主进程读取新内容
          path: ./proxy/nginx.conf # 只针对代理配置，不扩大监听范围
          target: /etc/nginx/conf.d/default.conf # 容器内的实际配置位置

可以按这个判断：热加载框架能直接读取的源码优先用 sync；需要安装或编译依赖的清单用 rebuild；不需要重建镜像、但主进程必须重新读取的配置用 sync+restart。

启动 Watch 并确认可见状态

1. 在包含 compose.yaml 的项目目录执行 docker compose up --watch。它会构建并启动服务，同时开启文件监视。
2. 编辑 ./web 下的一个源码文件并保存。规则匹配后，Compose 应把变化同步到 /app/web。
3. 修改 package.json 时，不要只等待同步；它应进入 rebuild 规则，重新构建服务。
4. 如果不希望服务日志与同步事件混在一起，也可以使用专用的 docker compose watch 命令。

这里的确认点是“规则命中了正确动作”，不是把一次编辑误认为所有类型的文件都能热更新。停止开发环境时执行：

docker compose down # 停止并移除本次开发启动的服务容器

没有同步时先查这三个边界

第一，检查路径：path 相对项目目录，ignore 又相对当前规则的监听路径，写错层级就会看起来像 Watch 没有工作。第二，检查镜像工具和权限：Watch 依赖容器中的 stat、mkdir、rmdir，并要求运行容器的用户能够写入 target。第三，检查是否把服务写成了只有 image 的预构建镜像；这种服务不属于本地源码构建场景。

如果镜像内目录由非 root 用户使用，Dockerfile 可以用 COPY --chown 让初始文件归属正确。不要为了“同步成功”把整个依赖目录取消忽略，也不要把需要重建的依赖变化伪装成普通源码同步。

相关问题

Compose Watch 和 bind mount 是一回事吗？不是。Watch 可以按规则精确同步并忽略目录，适合容器化开发；bind mount 是主机目录共享机制，两者可以按项目需求配合使用。

为什么修改依赖文件后没有立即生效？依赖安装属于镜像构建阶段，应该为依赖文件设置 rebuild，而不是期待 sync 自动安装。