Docker Compose up只重建指定服务

在一个同时包含 web、api、db 的 Compose 项目里，修改了 api 后，不需要把整套服务停掉再启动。直接把服务名放在命令末尾即可：

# 只选择 api 服务；-d 让服务在后台运行
docker compose up -d api

Compose 会处理 api 以及它声明的必要依赖；如果目标服务的配置或镜像发生变化，已有目标容器可能被停止并重新创建。真正需要“只处理一个服务”时，还要根据依赖关系选择参数。

官方地址：https://docs.docker.com/compose/

记住两个范围：服务名决定“选哪些服务”，--no-deps、--force-recreate 等参数决定“依赖是否启动、容器是否重建”。

1. 先确认 Compose 服务名

命令使用的是 compose.yaml 中 services 下的键，不是 docker ps 里看到的完整容器名。比如文件中有 web、api、db 三项，目标就应写成 api。

先列出当前项目状态，可以避免把服务名写错：

# 查看当前项目中的服务、容器状态和端口映射
docker compose ps

如果输出中没有目标服务，先检查当前目录和 -f 指向的 Compose 文件；不要用容器随机生成的名称替代服务名。

2. 只启动并更新目标服务

最常用的写法是把服务名放在最后：

# api 配置或构建上下文有变化时，让 Compose 按规则更新 api
docker compose up -d api

# 修改了 api 的 Dockerfile 或构建目录时，先构建再启动 api
docker compose up -d --build api

这里的“只”指选择了 api，并不保证依赖永远不动。如果 api 的 depends_on 指向 db，Compose 可能先启动 db；依赖服务满足健康条件后，才继续处理目标服务。依赖被启动和依赖被重建是两件事。

3. 按场景控制依赖和重建

下面几组命令适合不同的修改范围：

--no-deps 不是“只重建 api”的同义词，而是“不启动依赖”；依赖不可用时，api 仍可能启动失败。相反，--force-recreate 只作用于 Compose 选中的服务范围，不会自动把所有项目服务都重建。

4. 用可见状态核对结果

启动完成后，至少核对目标服务和依赖服务的状态：

# 查看服务是否处于运行状态，并确认目标服务没有退出
docker compose ps

# 查看 Compose 识别到的服务镜像，辅助判断 --build 是否产生了新镜像
docker compose images api

如果 api 的容器状态正常、依赖仍为运行状态，并且镜像与本次构建相符，就达到了“只更新目标服务”的操作目标。不要只看命令返回成功；容器随后退出时，还应读取目标服务日志。

# 只跟踪目标服务日志，定位启动后立即退出的原因
docker compose logs --tail=100 api

常见误区与回退方式

误区一：把项目名或容器名当服务名。回到 Compose 文件的 services 键确认。

误区二：以为 --no-deps 会跳过所有依赖检查。它只阻止依赖服务启动，不能替代网络、数据库和环境变量配置。

误区三：用了 --no-recreate 却期待新镜像进入旧容器。如果必须让新镜像生效，去掉该参数，或明确使用 --force-recreate。

需要撤回本次目标服务的运行容器时，可以先停止它，再按原命令重新启动；不要直接对整个项目执行 down，除非确实要移除整套项目资源。

相关问题

Q：只写一个服务名，会不会把所有服务都重建？
不会。Compose 只选择该服务及必要依赖；但依赖可能被启动，配置变化时也可能触发对应处理。

Q：什么时候用 --no-deps？
依赖已经稳定运行，且这次只想替换目标服务容器时使用；首次启动或依赖不确定时不要盲加。

Q：改了 Dockerfile 后为什么容器里还是旧代码？
使用 docker compose up -d --build api，再用 docker compose images api 和日志确认构建、启动结果。