wait-for-it能解决依赖启动卡死，关键在于它不靠猜时间，而是真实检测目标服务端口是否可连通；只要配置得当——设合理超时、加--strict模式、用exec接管pid 1——就不会无限等待或过早执行。
wait-for-it 能解决依赖启动卡死，关键在于它不靠猜时间，而是真实检测目标服务端口是否可连通。只要配置得当，就不会无限等待或过早执行。
为什么卡死？常见错误配置
很多卡死不是工具问题，而是用法不当：
- 没设超时参数（-t）：默认15秒，但若目标服务根本起不来，脚本会等满15秒后失败退出——如果应用没处理这个退出码，可能就停在那里不动了
- 用了 -t 0 却没兜底逻辑：无限等待看似保险，但一旦 db 容器因配置错误根本无法监听 5432 端口，脚本就会一直循环探测，容器状态卡在 “Starting”
- host 名写错或 DNS 不通：比如写成 database:5432，但 compose 中服务名是 db，DNS 解析失败，连接尝试立刻报错，重试间隔内反复失败，日志刷屏却无进展
-
命令写在 entrypoint 里但没加 exec：例如用
./wait-for-it.sh db:5432 -- npm start，npm start 启动后父进程（wait-for-it）还活着，容器 PID 1 不是 npm，导致信号转发异常、无法优雅停止
正确用法：避免卡死的三步设置
核心原则：有超时、有健康判断、有执行接管。
-
必须指定合理超时：例如
-t 60给 PostgreSQL 充足初始化时间；若确定环境稳定，也可设-t 30防止长阻塞 - 加上 --strict 模式：确保只有端口真正通了才执行后续命令，避免“以为通了其实只是端口开了但服务挂了”的假成功
-
用 exec 启动主进程：写成
./wait-for-it.sh db:5432 --strict -- exec npm start，让 npm 成为 PID 1，容器生命周期由它控制
配合 Docker Compose 的稳妥写法
光靠 wait-for-it 还不够，建议和健康检查联动：
- 在 db 服务中定义
healthcheck，用pg_isready或mysqladmin ping真实验证服务可用性 - app 服务中仍保留 wait-for-it，作为启动瞬间的快速探活（弥补 healthcheck 初始延迟）
- 这样即使 healthcheck 还没上报 healthy，wait-for-it 也能抢在应用代码第一次 connect 前完成等待
调试卡死：看这三处日志
遇到卡住，别急着重启，先查：
- 容器日志开头几行：有没有 “waiting for db:5432”、“timeout reached” 或 “connection refused”
-
db 容器的 healthcheck 状态：运行
docker-compose ps，看 db 列是否显示healthy -
网络连通性：进 app 容器执行
nc -zv db 5432，确认底层 TCP 是否真能通
