depends_on仅控制容器启动顺序，不保证服务就绪；必须配合healthcheck与service_healthy条件，或wait-for-it.sh脚本及应用层重试机制才能可靠等待依赖服务可用。
depends_on 不能保证服务就绪，只控制容器进程启动顺序——这是 Docker Desktop（含 Compose v2）里最常被误解的一点。你配了 depends_on 却还是连不上数据库？不是配置错了，是漏掉了健康检查和等待条件。
depends_on 只管“容器跑没跑”，不管“服务行不行”
在 docker-compose.yml 里写 depends_on: [db]，Docker Desktop 会先 docker start db，等它状态变成 running，再启动 web 容器。但 PostgreSQL 容器刚 running 时，可能还在初始化数据目录、加载扩展、监听端口——pg_isready 还会返回 no response。
常见错误现象：
- web 容器启动报错：
connect ECONNREFUSED 172.20.0.2:5432 -
docker-compose ps显示db状态是Up 2s，但日志里还没看到database system is ready to accept connections - 手动
docker exec -it web sh后telnet db 5432通了，但应用仍连不上（说明端口通≠服务可连接）
必须加 healthcheck + condition: service_healthy
给依赖服务（如 db）配健康检查，并让上游服务明确等待其 healthy 状态，这才是 Docker Desktop 原生支持的可靠方案。
PostgreSQL 示例：
db:
image: postgres:15
environment:
POSTGRES_PASSWORD: example
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30sweb 服务写法：
web:
build: .
depends_on:
db:
condition: service_healthy注意点：
-
start_period: 30s很关键：PostgreSQL 首次启动可能需要 20+ 秒初始化，不设这个，健康检查会在真正准备好前就失败多次，导致状态卡在unhealthy - Docker Desktop（Compose v2.20+）默认启用
service_started，但service_healthy必须显式写，不能省略 - 用
docker inspect <container> | jq '.State.Health'</container>可验证健康状态是否真的变healthy
老镜像或复杂就绪逻辑，用 wait-for-it.sh 补位
如果依赖服务镜像不支持自定义 healthcheck（比如某些私有 Java 服务），或者你需要判断 HTTP 返回码、JSON 字段等，就得靠外部脚本探测。
操作步骤：
- 下载
wait-for-it.sh到项目根目录：wget https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh - 给执行权限：
chmod +x wait-for-it.sh - 挂载进容器并改启动命令：
web:
build: .
volumes:
- ./wait-for-it.sh:/wait-for-it.sh
command: sh -c "./wait-for-it.sh db:5432 --timeout=60 -- npm start"关键细节：
- 超时时间
--timeout=60建议设为健康检查start_period的 2 倍以上，避免脚本比服务还早放弃 - 不要用
telnet或nc简单测端口——很多服务端口开了但内部未就绪（如 Spring Boot Actuator 未启动） - 脚本轮询日志会刷屏，生产环境建议加
--quiet抑制中间输出
应用层重试仍是最后一道保险
即使 Compose 层做了 service_healthy 等待，网络抖动、连接池冷启动、DB 连接数打满等情况仍会导致首次请求失败。
所以应用代码里该有的逻辑不能省：
- 数据库客户端开启连接重试（如 TypeORM 的
retryAttempts: 5） - HTTP 客户端对依赖服务 API 加指数退避重试（如 axios-retry）
- 避免在
index.js顶层同步await db.connect()，应包装成带重试的初始化函数
最易被忽略的是：健康检查通过 ≠ 所有连接都可用。PostgreSQL 的 pg_isready 只验证本地连接，而你的应用走的是网络连接，DNS 解析、iptables 规则、甚至容器网络插件延迟都可能引入新失败点——别把所有信任都交给编排层。
