Linux shell 管道失败状态怎样向上返回

在 Linux 脚本里，cmd_a | cmd_b 看起来像一条完整命令，但 Bash 默认只把最后一个命令的退出状态交给外层脚本。于是前面的命令已经失败，后面的命令仍返回 0 时，脚本就可能误以为整条管道成功。解决办法是启用 pipefail；需要定位每一段时，再立即读取 PIPESTATUS。

本文只讨论 Bash，不把 /bin/sh 当成 Bash 使用。示例重点是失败状态如何向上返回，以及哪些场景不应该让预期失败直接终止脚本。

默认管道为什么会漏掉中间失败

Bash 手册把管道描述为由 | 或 |& 连接的一组命令。默认情况下，管道的退出状态等于最后一个命令的状态。下面这条命令即使左侧读取失败，右侧的过滤命令仍可能正常结束。

#!/usr/bin/env bash

# 这里只演示状态传播，不依赖真实文件或网络输入。
false | true
printf '默认管道状态：%s\n' "$?"

这里的关键不是命令本身，而是观察边界：外层脚本只拿到最后一个命令的返回值。若前面的命令负责读取、解压或转换，错误就可能被安静地吞掉。

启用 pipefail，把失败传到管道外层

pipefail 是 Bash 的 set -o 选项。启用后，只要管道中有命令返回非零，整体就不会被最后一个成功命令覆盖；多个失败时，结果取最右侧那个非零状态。

#!/usr/bin/env bash

# 让管道暴露其中的失败状态，便于外层脚本统一处理。
set -o pipefail

false | true
pipeline_status=$?
printf '启用 pipefail 后：%s\n' "$pipeline_status"

# 只在整体失败时退出，保留清晰的错误提示。
if (( pipeline_status != 0 )); then
  printf '管道失败，状态码=%s\n' "$pipeline_status" >&2
  exit "$pipeline_status"
fi

工程脚本常把它和 set -u、set -e 放在一起，但三者职责不同：pipefail 改变管道状态的计算方式，set -e 才决定某些非零状态是否让脚本退出。先分清两层，排查会更快。

用 PIPESTATUS 区分每一段命令

整体状态适合让调用方判断成功或失败；如果需要知道究竟哪一段失败，要在管道结束后立即读取 Bash 的 PIPESTATUS 数组。任何会改变后续命令的操作都可能覆盖这组状态，因此不要先执行 printf 或条件判断再读取。

#!/usr/bin/env bash

# pipefail 负责整体失败，PIPESTATUS 负责保留各段状态。
set -o pipefail

false | true
statuses=("\${PIPESTATUS[@]}")
pipeline_status=0
for status in "\${statuses[@]}"; do
  # 复现 pipefail：记录最右侧的非零状态。
  if (( status != 0 )); then
    pipeline_status=$status
  fi
done

# 复制数组后再打印，避免后续命令改变 PIPESTATUS。
printf '命令 A=%s，命令 B=%s，整体=%s\n' \
  "\${statuses[0]}" "\${statuses[1]}" "$pipeline_status"

这个写法有一个细节：读取数组本身之后，$? 已不再可靠地代表刚才的管道，所以示例先复制 PIPESTATUS，再从数组计算最右侧非零状态。生产脚本也可以只保存自己真正需要的一类状态，避免在诊断代码里引入新的副作用。

反例：set -e 不是 pipefail 的替代品

只写 set -e，并不会自动改变管道整体状态的计算规则。没有 pipefail 时，左侧失败而右侧成功的管道仍可能整体返回 0，脚本也就没有触发退出条件。

反过来，打开 set -e -o pipefail 后，预期中的探测失败也可能让脚本提前结束。例如“尝试读取旧配置，失败则使用默认值”本来是允许失败的分支，就不应直接裸写成一条严格管道。可以把它放进明确的条件位置：

#!/usr/bin/env bash

# 严格模式用于主流程，但把允许失败的探测放在条件位置。
set -euo pipefail

if result=$(some_probe_command | some_filter_command); then
  printf '探测得到：%s\n' "$result"
else
  # 这里的失败是预期分支，使用默认配置继续。
  printf '探测未命中，使用默认配置\n' >&2
fi

判断清单很简单：需要让中间失败可见时启用 pipefail；需要区分具体命令时立即保存 PIPESTATUS；需要允许失败时放进 if、|| 等明确语境；脚本解释器不是 Bash 时，不要直接假定这些选项存在。

总结：把状态传播设计成脚本边界

管道不是天然的成功单元，默认规则只关注最后一段。对 Bash 脚本来说，最小可靠组合是：在脚本边界启用 set -o pipefail，在需要诊断时紧接着保存 PIPESTATUS，再把预期失败放进显式条件。这样既能避免错误被吞掉，也不会把所有非零状态都误判成异常。

常见问题

pipefail 会让每一段命令都立即停止吗？

不会。它改变的是管道整体退出状态，不负责终止已经启动的命令；是否因非零状态退出，还要看 set -e 或脚本自己的判断。

为什么读取 PIPESTATUS 后再看 $? 会不对？

PIPESTATUS 是 Bash 的状态数组，后续命令可能更新状态上下文。需要同时记录整体状态和分段状态时，应在管道结束后立刻保存，并避免在保存前插入输出或其它命令。