参数是干什么的
docker compose up 加 --wait 后会等到所有服务达到 running 或 healthy 状态才返回。判定依据是服务的 healthcheck：配置了健康检查的按健康状态判定，没配置的只看容器是否处于运行状态。它适合 CI、发布脚本与自动化测试，用来替代「起容器后 sleep 一段时间」这种不可靠的等待方式。
基本信息
| 用途 | 等待所有服务就绪后再返回 |
|---|---|
| 语法 | docker compose up -d --wait [--wait-timeout 秒] |
| 判定依据 | 有 healthcheck 的服务按健康状态，其余按 running |
| 失败行为 | 超时或服务异常时以非零退出码结束 |
| 适用平台 | Docker Compose v2 |
典型使用场景
- CI 部署后紧跟接口冒烟测试，需要服务真正可用
- 先起数据库并等其健康，再执行迁移任务
- 自动化测试前置：确保被测服务就绪再发请求，减少随机失败
- 发布脚本串联多阶段部署，避免用固定 sleep 猜时间
- 灰度切换前做一次就绪校验
服务侧健康检查
服务侧健康检查
services:
api:
image: app/api:1.4.2
healthcheck: # 缺少它时 --wait 只能判断容器是否在运行
test: ['CMD', 'curl', '-fsS', 'http://localhost:8080/healthz']
interval: 5s
timeout: 3s
retries: 6
start_period: 20s等待与验证
等待与验证
docker compose up -d --wait --wait-timeout 120 # 全部服务就绪才返回
echo $? # 非零表示有服务没起来或未通过健康检查
docker compose ps --format '{{.Name}} {{.Status}}'
docker compose ps --status running # 只看运行中的服务参数取值
| 参数 | 含义 | 取值提示 |
|---|---|---|
| --wait | 等待就绪后才返回 | 需要健康检查才有实际的就绪语义 |
| --wait-timeout | 最长等待秒数 | 不设可能长时间挂住，CI 里建议显式设置 |
| healthcheck.interval | 健康检查间隔 | 间隔越大，就绪判定越滞后 |
| healthcheck.retries | 连续失败次数阈值 | 与 start_period 配合，避免启动慢被误判 |
返回码是关键信息：等待过程中出现失败会以非零退出码结束，脚本必须把它当成发布失败处理，忽略退出码就等于放弃了这层保护。
启动较慢的服务应设置 start_period，让预热期内的健康检查失败不计入重试次数，否则会在应用还没准备好时就被判为不健康。