depends_on 是什么
depends_on 声明服务之间的启动依赖。短语法只保证容器的启动先后顺序，长语法配合 condition 才能真正等待依赖就绪：等健康检查通过，或等一次性任务以退出码 0 结束。这是它最容易被误用的地方。
基本信息
| 短语法 | depends_on: [db]，只按顺序启动容器 |
|---|---|
| 长语法 | condition: service_started / service_healthy / service_completed_successfully |
| 前提 | service_healthy 要求被依赖服务定义了 healthcheck |
| 方向 | 只表示本服务依赖上游，不反向生效 |
| 循环依赖 | 成环时 compose 报 dependency cycle detected 拒绝启动 |
典型使用场景
- 应用启动前等数据库就绪：配 service_healthy，避免应用连不上数据库直接退出
- 数据库迁移先于应用：用 service_completed_successfully 等迁移跑完再拉起应用
- 本地开发时保证缓存、消息队列先起，减少启动初期的报错噪音
- CI 里按依赖顺序起测试依赖服务，跑完统一 down 清理
- 给依赖补上 healthcheck，把模糊的启动顺序问题变成可判断的就绪问题
- 把服务拓扑显式写进文件，让 compose 文件顺带承担一部分架构说明的职责
示例
示例
services:
api:
image: app/api:1.4.2
depends_on:
migrate:
condition: service_completed_successfully # 等迁移任务成功结束
db:
condition: service_healthy # 等数据库检查通过
cache:
condition: service_started # 只要求容器已启动
db:
image: postgres:16-alpine
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
retries: 10三种 condition 的含义
| 取值 | 等待到什么程度 | 适用场景 |
|---|---|---|
| service_started | 容器已启动 | 不要求就绪的弱依赖 |
| service_healthy | 健康检查通过 | 数据库、消息队列等需要就绪才能连 |
| service_completed_successfully | 容器以退出码 0 结束 | 数据库迁移、初始化脚本 |
短语法下容器启动了并不代表服务可用，应用启动握手失败的多数原因就在这里；改成 service_healthy 通常比在应用里堆重试更省事。
condition 只在 compose 本地启停时生效，编排进集群后依赖语义不同；应用自身仍应保留连接重试，覆盖依赖中途重启的情况。
depends_on 只作用于项目的启动阶段：docker compose restart 只重启指定服务，不会连带把它的上游一起拉起来，重启后仍要自己确认依赖状态。