depends_on仅控制容器启动顺序，不等待服务就绪；需应用层重试或healthcheck配合service_healthy条件。MySQL健康检查start_period需与应用连接超时协同，避免首次连接即失败。
单纯靠 depends_on 不能让应用等数据库“准备好”，它只控制容器启动顺序，不检查服务是否就绪。 这是本地开发中最常踩的坑——web 容器一启动就去连 mysql，但 MySQL 还在初始化、建库、加载数据，连接直接被拒，日志里满屏 Connection refused 或 Access denied。
为什么 depends_on 不够用
Docker Compose 的 depends_on 只确保目标容器的 docker start 命令已执行完毕，并不等待其内部服务（如 MySQL 的 3306 端口真正可响应 SQL 请求）。MySQL 启动后可能还要花几秒加载系统表、恢复事务日志，甚至执行 init.sql 脚本。这个过程完全不在 Docker 的感知范围内。
-
depends_on是容器生命周期层面的依赖，不是服务健康层面的依赖 - 官方文档明确写：“
depends_ondoes not wait fordbto be ‘ready’” - 现象：
docker-compose up显示所有容器Up，但应用日志仍在疯狂重试数据库连接
应用侧加健康检查重试（推荐首选）
最轻量、最可控的方式：让应用自己处理连接失败，而不是把责任推给编排工具。几乎所有主流框架都有现成方案。
- Node.js（Express + mysql2）：用
mysql.createPool({ waitForConnections: true, connectionLimit: 10 })+ 自动重连逻辑，或封装await connectWithRetry()函数 - Python（FastAPI + SQLAlchemy）：配合
sqlalchemy.exc.OperationalError捕获 +time.sleep()循环重试，或用tenacity库做指数退避 - Java（Spring Boot）：
spring.datasource.hikari.connection-timeout和spring.datasource.hikari.initialization-fail-timeout控制初始化行为；更稳妥的是启用spring-boot-starter-jdbc的自动重试机制 - 通用原则：首次连接失败不 panic，最多等 30 秒，每 2–3 秒重试一次，超时后才抛致命错误
用 healthcheck 配合 depends_on 来约束启动时机
如果必须让 web 容器等 MySQL 真正“活”了再启动，就得在 docker-compose.yml 里补上健康检查定义，并让 depends_on 引用它：
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-pexample"]
timeout: 20s
retries: 10
start_period: 40s
web:
build: .
depends_on:
db:
condition: service_healthy
-
test命令必须能真实反映服务可用性，mysqladmin ping比curl http://db:3306有效得多 -
start_period要足够长（MySQL 冷启动常需 20–30 秒），否则健康检查还没开始就判定失败 - 注意：Docker Desktop 的 Dashboard 会显示
db状态从starting→unhealthy→healthy，这是正常过程 - 该方式会拖慢整体启动速度，仅建议用于 CI 或严格依赖顺序的测试场景
避免用 wait-for-it.sh 类脚本污染镜像
虽然网上大量教程教你在 web 容器启动前跑 ./wait-for-it.sh db:3306 -- npm start，但这属于反模式：
- 把运维逻辑硬编码进应用镜像，违反“一个容器一个进程”原则
- 脚本本身可能有 bug（比如没处理 DNS 解析延迟），反而掩盖真实问题
- 调试困难：你得同时看脚本日志和应用日志，出错时分不清是谁的问题
- 现代语言生态已有更优雅的重试机制，没必要倒退回去用 shell 脚本兜底
真正容易被忽略的是：**健康检查的 start_period 和应用自身的连接超时设置必须协同**。比如 MySQL 的 start_period: 40s，那你的 Node.js 应用 connectTimeout 就不该设成 5000ms —— 否则第一次连接永远失败，重试逻辑根本没机会触发。这两个时间点要对齐，才是本地开发顺滑的关键。
