Docker Compose Watch 的 rebuild 和 sync+restart 怎么选

Docker Compose Watch 的选择可以先记成一句话：能被开发服务器热加载的源代码用 sync；文件内容变了但只需要让进程重新读配置，用 sync+restart；改动会影响依赖、构建步骤或镜像内容，用 rebuild。不要因为“文件变了”就统一重建，重建会重新生成镜像并替换服务，反馈更慢。

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

步骤一：先按改动影响划分文件

我在开发容器里遇到过一个典型误区：改了应用代码却触发整套镜像构建，或者改了配置只同步文件却没有让主进程重新读取。判断动作时不要看文件后缀，而要看改动是否改变镜像、是否需要重启进程。

同步范围也要收窄。Docker 官方文档说明，watch 路径相对项目目录，目录会递归监听；.dockerignore 规则仍会生效，ignore 可以继续排除不应同步的目录。通常不要同步 node_modules、构建产物和缓存。

步骤二：为可热更新代码配置 sync

服务必须使用 build 从本地源代码构建，watch 不会替使用预构建 image 的服务追踪本地改动。下面的规则让 web/ 下的源文件同步到容器，依赖目录继续忽略：

services:
  web:
    build: .
    command: npm start
    develop:
      watch:
        # 源代码变化只同步，不替换容器
        - action: sync
          path: ./web
          target: /app/web
          initial_sync: true
          ignore:
            # 依赖通常包含宿主机平台相关的原生模块
            - node_modules/

保存源文件后，正确的确认信号是容器仍然运行，目标路径出现新内容，前端热更新或开发服务器重新加载。若每次修改都看到镜像构建，先检查规则是否误写成 rebuild，或者路径是否覆盖了依赖文件。

步骤三：为配置文件配置 sync+restart

配置文件不一定需要重新构建镜像。比如 nginx 配置已经被复制到目标目录，变化后只要同步并重启 nginx 进程即可：

services:
  web:
    build: .
    develop:
      watch:
        # 页面代码继续走热更新
        - action: sync
          path: ./web
          target: /app/web
        # 配置同步后重启主进程，让新配置被读取
        - action: sync+restart
          path: ./proxy/nginx.conf
          target: /etc/nginx/conf.d/default.conf

sync+restart 的边界是“需要重新启动进程，但不需要生成新镜像”。如果配置文件本身由 Dockerfile 的 COPY、安装步骤或构建参数决定，就应把它归到 rebuild，不能只靠重启掩盖旧镜像。

步骤四：为依赖和镜像输入配置 rebuild

新增依赖不能在容器里凭空出现。依赖清单、Dockerfile 和会改变构建上下文的文件应触发重建。一个常见配置如下：

services:
  web:
    build: .
    command: npm start
    develop:
      watch:
        # 依赖变化必须重新构建并替换服务容器
        - action: rebuild
          path: package.json
        # 锁文件改变时也要让镜像重新解析依赖
        - action: rebuild
          path: package-lock.json

官方文档把 rebuild 定义为使用 BuildKit 重新构建镜像，并替换正在运行的服务，效果相当于对该服务执行 docker compose up --build。旧镜像默认会清理为 dangling image；需要保留时再考虑 docker compose watch --prune=false，不要把它当作日常热更新开关。

步骤五：用命令和日志核对结果

在项目目录启动 watch：

# 启动服务并同时开启文件监听
docker compose up --watch

# 如果不想把应用日志和同步、构建事件混在一起
docker compose watch

第一次调整规则时，我更愿意分别修改一类文件观察事件：改源文件应看到同步；改 nginx.conf 应看到同步后重启；改依赖清单应看到构建并替换服务。若动作不对，优先检查 path 是否相对项目目录、target 是否对应容器目录，以及服务是否有可用的 stat、mkdir、rmdir 和目标路径写权限。

常见问题

sync+restart 能替代 rebuild 吗？

不能。它只同步文件并重启容器进程，不会重新执行 Dockerfile 或安装依赖。只要改动影响镜像层、依赖解析或构建参数，就应使用 rebuild。

为什么只改 package.json 也要 rebuild？

运行中的容器不会因为宿主机依赖清单变化就自动安装新依赖。rebuild 会重新生成镜像并替换服务，才能让依赖进入可重复的镜像状态。

sync 和 bind mount 有什么区别？

bind mount 直接共享主机目录，watch 则按规则同步，并能对文件和目录设置更细的 ignore。跨平台开发或不想同步大量原生依赖时，watch 更容易控制范围。

最终判断标准不是“命令运行了”，而是动作与改动类型匹配：代码只同步，配置同步后重启，依赖和镜像输入重新构建。把三类路径拆开，Compose Watch 才能同时获得较快反馈和可重复的容器环境。