depends_on 是什么
depends_on 声明服务之间的启动依赖。短语法只保证容器创建与启动的先后顺序，并不保证被依赖的服务已经「就绪」——数据库容器起来了但还在初始化表结构，应用这时连过去照样报错。长语法配合 condition 才能真正做成启动门闩，其中 service_healthy 要求被依赖服务先通过健康检查。
基本信息
| 短语法 | depends_on 后跟服务名列表，仅控制创建与启动顺序 |
|---|---|
| 长语法条件 | service_started、service_healthy、service_completed_successfully |
| service_healthy 前提 | 被依赖服务必须配置 healthcheck，否则无法判断健康 |
| 失败行为 | 依赖服务启动失败时不会自动重试本服务，需要应用自身重连 |
| 升级提示 | 旧版 compose 文件语法与新版实现存在差异，以当前版本文档为准 |
典型使用场景
- 应用等数据库：用 service_healthy 保证连接时数据库已可接受连接
- 迁移任务先行：用 service_completed_successfully 等数据库迁移跑完再起应用
- 缓存预热：等缓存服务就绪后再启动依赖它的应用
- 调试依赖链：临时调整依赖顺序，快速定位是哪一步卡住
- 减少误报：避免应用在依赖初始化阶段反复报连接错误干扰排查
可靠等待示例
可靠等待示例
services:
web:
image: myweb:1.0
depends_on:
db:
condition: service_healthy # 等数据库健康检查通过
db:
image: mysql:8.0
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1"]
interval: 5s # 检查间隔
timeout: 3s # 单次检查超时
retries: 20 # 连续失败次数上限
start_period: 30s # 初始化宽限期，避免早失败三种条件的语义
| 条件 | 触发时机 | 适用场景 |
|---|---|---|
| service_started | 依赖服务进程已启动 | 无健康检查、仅需顺序 |
| service_healthy | 依赖服务健康检查通过 | 数据库、缓存等需要就绪的服务 |
| service_completed_successfully | 依赖任务成功退出 | 数据库迁移、初始化脚本、构建任务 |
编排不是银弹：应用侧仍要实现连接重试与退避。依赖服务短暂抖动或重启时，没有重连逻辑的应用会直接退出，整栈启动随之失败。
健康检查命令必须是被依赖容器内真实存在的可执行程序：命令不存在会让容器永远处于不健康状态，依赖它的服务则一直卡在启动前，表现为「没有报错但就是起不来」。