timeout 是什么
timeout 属于 coreutils，把命令放进限时容器里执行：到点未结束就按指定信号终止它。脚本里凡是可能挂住的动作（网络探测、外部接口调用、锁等待、交互式命令）都应该包一层 timeout，这样失败是可控的、可预测的，而不是让整个任务无限期卡住。
基本信息
| 适用平台 | Linux/Unix（coreutils；macOS 需通过 gtimeout 或 brew 安装） |
|---|---|
| 命令语法 | timeout [选项] 时长 命令 [参数...] |
| 常用选项 | -s 指定信号（默认 TERM）-k 发出信号后再等待的宽限秒数 --foreground 在前台进程组中运行 |
| 时长写法 | 默认单位秒，也支持 5s、2m、1h 这样的后缀 |
| 退出码 | 0 正常结束、124 超时被终止、125 timeout 自身失败、126 不可执行、127 命令未找到 |
典型使用场景
- 网络探测：给探测命令设上限，避免防火墙丢弃导致长时间等待
- 调用外部接口：防止对端不响应拖死整条流水线
- 锁与队列等待：等待超时即放弃并转入补偿逻辑
- 批处理保护：整段脚本加总时限，防止个别步骤失控
- 运维动作兜底：重启、检查类命令加限时，避免卡在半途
常用示例
常用示例
timeout 10 curl -sS http://10.0.0.9/health # 10 秒内必须返回
timeout -s KILL 5 ./hang.sh # 超时直接 KILL
timeout -k 5 10 ./slow.sh # 先 TERM，5 秒后升级为 KILL
timeout 30 bash -c 'nc -z -w 25 10.0.0.9 443' # 整体限时
timeout 2m ./sync.sh # 支持分钟等单位后缀
timeout 1 sleep 5; echo $? # 输出 124，可用于判断超时退出码读法
| 退出码 | 含义 | 处理 |
|---|---|---|
| 0 | 命令在时限内正常结束 | 按命令自身的业务含义继续判断 |
| 124 | 命令被 timeout 终止（超时） | 进入超时分支：重试、告警或降级 |
| 125 | timeout 自身执行失败 | 检查参数写法 |
| 126 | 命令存在但不可执行 | 检查执行权限与文件类型 |
| 127 | 命令未找到 | 检查路径与名称拼写 |
| 其它 | 命令自身的退出码 | 按该命令的约定解释 |
时长默认以秒为单位，也支持 5s、2m、1h 这样的后缀；配合 -k 5 表示信号发出后再等 5 秒，仍未退出就升级为 KILL，兼顾了优雅退出与确定性终止。
选信号要看场景：TERM 允许程序清理资源、落盘并删除临时文件，KILL 立即终止但可能留下锁文件与半写数据，所以对数据库类或写盘类命令应给足 -k 的宽限时间。需要被限时的命令要读取终端或接收终端信号时，还要加 --foreground。在流水线里给每个可能挂住的外部调用加限时，比事后排查「任务卡住」省事得多。