Docker Compose 修改配置后 restart 不生效的原因及正确做法

前言

在使用 Docker Compose 管理容器时，经常遇到一种情况：修改了 compose.yaml（或 docker-compose.yaml）中的配置（如端口、环境变量、卷挂载、command 等），执行 docker compose restart 后却没有任何变化。

核心原因

docker compose restart 仅重启已有容器，而不重新创建容器。

• 它相当于先执行 docker stop，再执行 docker start。
• 容器的许多关键配置（端口映射、环境变量、卷挂载路径、网络模式、restart 策略等）是在容器创建时（docker create 阶段）写入元数据的。
• restart 操作不会重新解析 compose.yaml 文件，也不会拉取新镜像或重建容器。

因此，凡是需要在创建阶段决定的配置，restart 都无法使其生效。

哪些修改受 restart 影响

修改类型	restart 是否生效	说明
容器内进程崩溃后的重启策略	通常不生效	创建时已固定
ports	不生效	端口绑定在创建时完成
environment / env_file	不生效	环境变量在创建时注入
volumes	不生效	挂载点在创建时确定
command / entrypoint	不生效	创建时写入
build 上下文 / Dockerfile 变更	不生效	需要重新构建镜像
image 标签变更（如 :latest 更新）	不生效	restart 不触发 pull
仅修改容器内部配置文件（volume 内）	生效	文件内容变化不依赖容器重建

使配置变更生效的正确方法

1. 针对单个服务快速应用变更（推荐）

docker compose up -d --build 服务名
# 或更强制
docker compose up -d --build --force-recreate 服务名

2. 应用所有变更（最常用）

docker compose up -d --build

Compose 会自动对比配置，仅重建有变化的服务。

3. 完全重置环境（开发 / 测试场景）

docker compose down
docker compose up -d --build
# 若需删除卷：
# docker compose down -v