← 返回首页

Shell 脚本九个静默失败:set -e 不生效,exit code 仍是 0

ShellBash脚本排错

上周一份发布脚本跑完,日志最后一行是 deploy finished,echo $? 给的是 0。但我去看产物目录,里面一个文件都没更新。回头翻日志才发现,cd 失败的那行早就打印过 No such file or directory,cp 也打印过 cannot stat——两条错误都在,脚本还是走完了全程,还给了个 0。

这不是 set -e 的 bug,是我对它的边界理解错了。set -e 的语义不是「任何一条命令失败就退出」,而是一份带豁免条款的规则表:条件测试里不算、|| 列表里不算、管道里除最后一段外不算、被 ! 取反时不算;函数一旦被当成条件,整个函数体都不算。这些豁免是 POSIX 与 bash 为了「if [ -d /foo ] 这类正常写法不被误杀」而加的,代价是失败会被安静地放过。

这篇把这一轮踩到的九处静默失败一次写完。全部在 Git Bash 自带的 bash 5.3.15(1)-release(构建目标 x86_64-pc-cygwin) 上实测,系统标识 MINGW64_NT-10.0-26300,每条都附退出码或磁盘结果,命令可以直接复制。它属于「退出码与真实结果之间的落差」这一层:已有几篇分别讲过进程退出码被截断(subprocess 的七个静默失效)、控制流的取消与超时(asyncio 取消与超时)、以及数据边界的解析(csv 的八个边界),本篇补的是 shell 这一层——脚本自己说成功,但它根本没做事。

本文不含任何联盟推广链接,文中不出现任何商品页。

TL;DR:set -e 有五类上下文完全不生效(if/while 条件、|| 与 && 列表、! 取反、管道非末段),函数被当条件时整个函数体都失去保护;local x=$(cmd) 的退出码是 local 自己的 0,会把失败吞掉;管道默认只看最右一段的退出码,pipefail 出厂是关的;$? 会被 local、if、echo 覆盖;命令替换里的 set -e 不继承(shopt -s inherit_errexit 才继承,bash 4.4 起);"$D/" 在 D 为空时就是 /,加引号救不了;管道里的 while 落在子 shell,计数器回到 0;here-doc 定界符不加引号会把 $ 与反引号当场展开,而它没闭合时 bash 只给一条 warning、退出码仍是 0。

// FLOW_01从「脚本说成功」到「真的成功」4 NODES01STEP_01复现一次 exit 0 的假成功02STEP_02逐个对照九处豁免上下文03STEP_03加上 pipefail 与 inherit_errexit04STEP_04用 trap ERR 兜底并回归验证END_OF_FLOW
从「脚本说成功」到「真的成功」 · 依据本文步骤自绘示意图
GitBash
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

一、先看一个 exit 0 的「成功」

先把症状做成可复现的最小脚本。下面这份是我当时的骨架,只把路径换成了 /opt/app/release,行号与报错文案都是实测原样:

#!/usr/bin/env bash
set -e
DIR=/opt/app/release
cd "$DIR" || true
note() { local out=$(cp missing.txt "$DIR/"); echo "copy done"; }
note
count=$(ls -1 "$DIR" 2>/dev/null | wc -l)
if [ "$count" -gt 0 ]; then echo "artifact ok"; fi
n=0
printf 'a\nb\n' | while read -r line; do n=$((n + 1)); done
echo "processed $n lines"
echo "deploy finished"

运行时($DIR 不存在,missing.txt 也不存在):

deploy-bad.sh: line 4: cd: /opt/app/release: No such file or directory
cp: cannot stat 'missing.txt': No such file or directory
copy done
processed 0 lines
deploy finished

三个事实摆在一起,互相矛盾:两条错误信息都打印了;copy done 在 cp 失败之后照常打印;脚本以 0 退出(echo $? 给 0),bash -n 的语法检查也给 0。

三处失败分别被三种机制吃掉:cd ... || true 是显式的 || 列表;local out=$(cp ...) 是 local 吞掉命令替换的退出码;printf | while read 是管道让计数器落在子 shell。下面逐条拆。

二、一号:`set -e` 有五个豁免上下文

bash 手册对 -e 的原文(The Set Builtin 一节)写得很清楚,先看英文原句:

The shell does not exit if the command that fails is part of the command list
immediately following a while or until reserved word, part of the test in an if
statement, part of any command executed in a && or || list except the command
following the final && or ||, any command in a pipeline but the last (subject to
the state of the pipefail shell option), or if the command's return status is
being inverted with !.

把这句话翻成可执行的判断:只要失败的那条命令站在「条件位置」上,set -e 就当没看见。实测六种写法,前五种全部以 0 退出:

失败命令所在位置实测结果脚本退出码
单独一行命令立即退出,后续不执行1
if 的条件位置存活,继续往下跑0
逻辑或列表的左项存活0
逻辑与列表的左项存活0
被 ! 取反存活0
while 的条件位置存活0

表格第一行是基线:裸的一行 false 确实会让脚本停。麻烦在于真实脚本里,失败几乎从不站在裸位置——它总在 if 里判断、在 || 后面兜底、在管道里被 tail 或 grep -q 收尾。也就是说,这五种豁免位置覆盖的正是生产脚本最常见的那部分写法:六种位置里五种不生效,5/6,约 83%。

这里还有一条容易被忽略的追加条款,紧跟在上面那段后面:

If a compound command or shell function executes in a context where -e is being
ignored, none of the commands executed within the compound command or function
body will be affected by the -e setting, even if -e is set and a command returns
a failure status.

这句是下一条的根。

三、二号:函数被当成条件,整个函数体失去保护

很多人以为「函数作为 if 的条件,函数内部还是会 set -e」。实测相反:

set -e
f() { false; echo "这一行居然执行了"; }
if f; then echo "then 分支"; fi

实测输出是两行都打印,函数返回 0——因为函数最后一条 echo 成功了,if 判断的是函数整体的返回值。函数体内那个 false 既没有终止函数,也没有改变返回值。

BashFAQ/105 里对这条的描述是:「As soon as a function is used as a conditional (in a list or with a conditional test or loop) set -e stops being applied within the function.」它同时提醒,这不仅会让本该停止的代码继续跑,还会改变函数的返回状态。

改法只有两条路:要么别把依赖 set -e 的函数放进条件位置,要么在函数里自己判断每一步。后者更可靠:

set -e
f() {
  false || return 1
  echo "只有前面成功才会到这里"
}
if f; then echo "then 分支"; fi

四、三号:`local x=$(cmd)` 把失败吞掉

这是本轮最难找的一处。两种写法只差一个分号,行为完全不同:

# 写法 A:失败被吞,继续跑,退出码 0
set -e
f() { local out=$(false); echo "A 继续执行"; }
f

# 写法 B:整脚本退出 1
set -e
f() { local out; out=$(false); echo "B 不该出现"; }
f

实测 A 打印「A 继续执行」并以 0 退出;B 一行都不打印,脚本退出码 1。差别来自 local:当它带赋值作为参数时,返回值是 local 自身的状态,而不是命令替换的状态。手册对 local 返回值的原文是「The return status is zero unless local is used outside a function, an invalid name is supplied, or name is a readonly variable.」——三种失败情形都与被赋值的命令无关。

BashFAQ/105 把这条与 export、declare、typeset 归为一类:「the exit status of local masks it (the assignment to the variable succeeds, so local returns status 0)」。

所以检查清单里应当有一条机械动作:全文搜 local 后面直接跟 = 的行。这类行要么拆成两行,要么显式加 || return 1。

五、四号:管道只看最右一段

bash 手册的 Pipelines 一节写:「The exit status of a pipeline is the exit status of the last command in the pipeline, unless the pipefail option is enabled.」而 pipefail 的默认值在同一份手册的 Set Builtin 一节:This option is disabled by default.

实测四组:

场景退出码说明
左段失败、右段成功0只看最后一段
同上,且已开 set -e0set -e 也救不了,管道整体是 0
同上,且已开 pipefail1取最右一个非 0
左段 exit 3、右段 exit 00左边的 3 完全不可见

第三行说明:set -e 与 pipefail 是两件不同的事,前者管「失败要不要退出」,后者管「管道整体算什么状态」。只开 set -e 不开 pipefail,管道左侧的失败对脚本完全不可见——这也是 tar czf - dir | gzip -d 之类写法最常见的坑。

pipefail 不是没有代价。它把左侧的失败也算进来之后,head 这类「读够就关管道」的命令会制造一个假失败:

set -eo pipefail
seq 1 200000 | head -n 1

这行在我的机器上打印了 1,然后整个脚本以 141 退出(128 + 13,SIGPIPE)。同一行去掉 pipefail 则以 0 退出。如果一定要这么写,得显式标注 || true,或者换成不提前关管道的写法。

六、五号:`$?` 已经被别的命令改掉了

$? 只保存「上一条命令」的状态,而 local、if、echo 都是命令。实测:

false; local x; echo "这里读到的是 $?"
false; if true; then :; fi; echo "这里读到的是 $?"

两行分别打印 0 和 0——false 的 1 早就不在了:local x 自己成功(返回 0),if 语句整体成功(返回 0)。真正能拿到 1 的写法是立刻存:

false
rc=$?
echo "rc=$rc"    # 打印 1

这条和上一条叠在一起最阴险:先用 local 吞掉失败,再用 $? 判断,读到的永远是 0,于是「有判断」的代码看起来也在正常工作。

七、六号:命令替换里 `set -e` 不继承

$(...) 在子 shell 里执行,子 shell 不会继承 set -e(除非显式打开):

set -e
x=$(false; echo inner)
echo "x=$x"     # x=inner,脚本退出码 0

实测输出 x=inner,退出码 0。也就是说命令替换内部前半段失败、后半段成功,外面完全看不到。打开 bash 4.4 起提供的选项之后行为才反转:

set -e
shopt -s inherit_errexit
x=$(false; echo inner)   # 这里直接以 1 退出,后面的 echo 不执行

实测命令行退出码从 0 变成 1。BashFAQ/105 的表述是「Subshells from command substitution unset set -e, however (unless inherit_errexit is set with Bash 4.4)」。我另外确认了本机默认值:shopt -p inherit_errexit 输出 shopt -u inherit_errexit,即默认关闭。

同一节手册还写了命令替换的另一个副作用:「replacing the command substitution with the standard output of the command, with any trailing newlines deleted」。实测 x=$(printf 'abc\n\n\n') 之后 ${#x} 是 3,三个换行全没了。所以凡是用 $(cat 文件) 拿内容再比对长度的校验逻辑,都是错的——这类比较必须走字节流(cmp、sha256sum,或者 $(< file) 加显式补尾换行)。

八、七号:空变量加了引号还是拼出根目录

引号能解决分词,不能解决「变量本身就是空的」这个问题:

D=""
printf '带引号: [%s]\n' "$D/"
printf '不带引号: [%s]\n' $D/

两种写法都打印 [/]。原因是 "$D/" 展开成空串拼斜杠,结果就是一个根路径。rm -rf "$DIR/" 这类写法在 DIR 为空时,目标就是 /——本文不演示这条命令,只用 printf 把展开结果打出来,谁都不该在自己的机器上验证它。

三种防护的实测差别:

写法结果
: "${D:?D is empty}"立即报 bash: line 1: D: D is empty 并以非 0 退出
[ -z "${D:-}" ] 后显式分支可控,推荐
${D%/} 剥尾斜杠空值仍然空,不解决问题

关键点是:${D:?} 是「空则报错」,${D%/} 只是「去掉一个尾斜杠」,后者常被当成防护,其实什么都没防。

九、八号:管道里的 `while` 在子 shell 里

这是一条经典,但它经常以「统计数字变成 0」而不是报错的形式出现:

n=0
printf 'a\nb\nc\n' | while read -r line; do n=$((n + 1)); done
echo "n=$n"

实测 n=0。原因是手册 Pipelines 一节的这句话:「Each command in a multi-command pipeline, where pipes are created, is executed in its own subshell」。循环里的 n 属于子 shell,父 shell 的 n 从头到尾没动过。

三种替代写法我实际测试过,结果一致(n=3):

# 其一:进程替换,循环留在当前 shell
n=0
while read -r line; do n=$((n + 1)); done < <(printf 'a\nb\nc\n')
echo "n=$n"

# 其二:bash 4.2 起的 lastpipe(需作业控制关闭,脚本里默认关闭)
shopt -s lastpipe
n=0
printf 'a\nb\nc\n' | while read -r line; do n=$((n + 1)); done
echo "n=$n"

# 其三:不需要流式时,直接用 for 遍历
n=0
for line in a b c; do n=$((n + 1)); done
echo "n=$n"

lastpipe 的适用条件在手册里也写了:「If the lastpipe option is enabled ... and job control is not active, the last element of a pipeline may be run by the shell process.」本机 shopt -p lastpipe 输出 shopt -u lastpipe,默认关闭,而交互式 shell 里作业控制默认开着,所以这条只在脚本里可靠。

十、九号:未加引号的 here-doc 定界符会展开

这条是我这一年里踩得最多的一条,也是唯一一条会「改写你写进去的内容」的。

bash 手册 3.6.6 节的原文:「If any part of word is quoted, the delimiter is the result of quote removal on word, and the lines in the here-document are not expanded. If word is unquoted, delimiter is word itself, and the here-document text is treated similarly to a double-quoted string.」

实测对照:

定界符写法落盘内容
不加引号unquoted: /c/Users/xuany and X
加单引号quoted: $HOME and $(printf X)

也就是说,用不带引号的定界符写一段「要落盘的脚本或配置」时,里面的 $变量、$(命令)、反引号会在我写文件的那一刻被执行掉,落盘的是执行结果,不是原文。更麻烦的是落盘结果往往是合法文本,语法检查也过得去,直到某个变量在别的机器上取不到值才暴露。

还有一条更隐蔽的:定界符没闭合时,bash 只给一条 warning,退出码仍是 0,而且它会把后面所有内容都当成 here-doc 的内容喂给命令。我构造了一个漏掉 EOF 的脚本实测:

w2.sh: line 2: warning: here-document at line 1 delimited by end-of-file (wanted `EOF')
body
w2 退出码=0

body 是被吞进去的内容,仍然被打印了;bash -n w2.sh 的退出码也是 0。这条 warning 必须被当成错误对待,否则脚本「跑完了」,内容却少了一大段。

十一、五个真实报错的原文与修法

下面五段都是我在本机跑出来的原样文案,连同退出码一起给出。

报错一:单引号数量不配对

w1.sh: line 1: unexpected EOF while looking for matching `"'

退出码 2。原因是一个引号没闭合,解析器一路读到底。修法:先跑 bash -n 脚本名(这类错误它返回 2,能拦住),再检查引号嵌套,尤其是把 SQL、正则、JSON 塞进单引号里的行。

报错二:here-doc 定界符没闭合

w2.sh: line 2: warning: here-document at line 1 delimited by end-of-file (wanted `EOF')

退出码 0——注意它只是一条 warning。修法见上一条:把定界符写成 'EOF' 并缩进对齐;用 <<-EOF 时注意它只剥制表符,用空格缩进同样不匹配。

报错三:if 少了 fi

w3.sh: line 3: syntax error: unexpected end of file from `if' command on line 1

退出码 2。bash 5.3 的措辞比老版本多了「from if' command on line 1」,会直接告诉你是哪一行开的头。修法:bash -n` 加上编辑器的高亮配对,不要靠缩进目测。

报错四:[ 收到空变量

bash: line 1: [: =: unary operator expected

退出码 2。原因是 [ $e = x ] 里 $e 为空,[ 只看到两个参数。修法有两种,任选其一但不要混用:

[ "$e" = x ]        # 加引号,让它成为空字符串
[[ $e = x ]]        # bash 的 [[ ]] 不做分词,空值安全

报错五:set -u 撞上未定义变量

bash: line 1: nope: unbound variable

退出码 1。位置参数也一样:set -u; echo "${1}" 在没有参数时给 bash: line 1: 1: unbound variable(写成 $ 后面直接跟数字的形态,文案里会连那个 $ 一起打印出来)。修法:可选值一律写默认值 ${nope:-},必填值用 ${nope:?nope is required}。顺带说一句,set -u 对 $@、$* 和空数组是安全的——实测 set -u 下遍历空数组、f "$@" 都不报错。

十二、让脚本真的停下来:可以照抄的头部

把上面九条翻成一段能用的头部,就这几行:

#!/usr/bin/env bash
set -euo pipefail
shopt -s inherit_errexit
trap 'echo "FAILED at line $LINENO: $BASH_COMMAND" >&2' ERR
IFS=$'\n\t'

实测效果:把开头那份失败脚本改成这版(并把 cd 与 note 改成显式判断),运行时立刻停下,退出码 1,并打印 no such dir: /opt/app/release。

逐行说明:-e 管失败退出、-u 管未定义变量、pipefail 让管道左侧失败可见;inherit_errexit 让命令替换内部也遵守 -e;trap ... ERR 提供出错位置(不加 set -E 时,ERR trap 不会进函数与命令替换,这一点手册在 -E 条里写明:「If set, any trap on ERR is inherited by shell functions, command substitutions, and commands executed in a subshell environment. The ERR trap is normally not inherited in such cases.」);IFS 收窄分词范围。

但这段头部并不等于安全。实测下来,九条里仍有几条能从它底下溜过去:

所以真正可靠的做法是把关键步骤改成显式判断,让判断本身成为失败点:

if ! out=$(cp src.txt "$DIR/" 2>&1); then
  echo "copy failed: $out" >&2
  exit 1
fi

实测 if ! out=$(false 2>&1); then 能稳定进入 then 分支,out=$(false) || { ... } 同样能捕获(退出码 1)。这两种写法不依赖 set -e 的豁免规则,读代码的人也不用背那张表。

十三、这份清单怎么用:四条自检

写完脚本后按顺序跑这四步,比事后读日志便宜得多:

另外把 bash -n 当成第一道闸,但要知道它能抓什么:未闭合引号返回 2、未闭合 if 返回 2、未闭合 here-doc 返回 0。第三项是它最容易放过的那一类。

十四、本文的边界:哪些结论我没测出来

为了让上面的数字能被复核,边界写清楚:

常见问题

Q:加上 set -euo pipefail 就安全了吗?

不是。它覆盖的是「命令失败要退出」这一层,管道子 shell、空值拼路径、未闭合 here-doc 三条都能绕过去。真正稳住的做法是关键步骤显式 if ! cmd; then,把那句判断当作唯一的失败点。

Q:为什么 local out=$(cmd) 不触发 set -e?

因为返回值是 local 自己的。手册写的是 local 在三种情况下才非 0:不在函数里用、变量名非法、变量只读。被赋值的命令失败与否不在其中。拆成 local out 与 out=$(cmd) 两行,第二行就是真实的命令退出码。

Q:读文件到底该用哪种循环?

需要变量留在当前 shell 的,用 while read -r line; do ...; done < 文件 或进程替换;只在脚本里且作业控制关闭时才考虑 lastpipe;不需要流式读取就直接 for line in ...。管道接 while 是唯一会静默丢计数的那种。

Q:set -e 还值得用吗?

值得,但必须配合显式判断。BashFAQ/105 的结论是「its rules are extremely convoluted」,并给了几种立场:有人建议不用、改用显式错误处理,有人认为可用但要清楚所有陷阱。我的做法是:小工具脚本用 set -euo pipefail 加 trap ERR,涉及产物与发布的脚本,关键步骤一律显式判断。

收尾

这九条的共同点不是「bash 有 bug」,而是「退出码只回答了一个非常窄的问题:最后一条命令有没有成功」。脚本说成功时,值得再问三件事:产物真的变了吗、错误信息是否被 || true 或 local 吃掉、判断用的 $? 是不是已经被覆盖。把这三问写成脚本里的断言,比给 set -e 再加一个选项有用。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页