本文说明脚本的错误处理、调试方法与工程规范。变量与展开见 变量与参数展开,流程控制与函数见 流程控制与函数,文本处理见 文本处理工具,信号与后台任务见 作业控制与信号,脚本执行与权限见 脚本执行,服务化运行见 systemd,定时任务见 计划任务与定时器,以最小权限运行的约束见 主机加固与登录安全,文件权限模型见 权限模型,变更与发布流程见 变更与发布管理,批量运维脚本的组织见 配置管理。

一、起源

1.1 失败的三种形态

形态 表现 危害
静默继续 中间步骤失败后脚本继续执行后续步骤 最终状态部分完成,且报错信息与实际原因无关
部分完成 前半段生效、后半段未生效 需要人工判断当前状态,恢复成本高
失败被掩盖 失败发生在管道中间或子 shell 中 退出码为成功,监控与调度无法感知

三种形态的共同原因是:Shell 默认不因命令失败而中止,退出码需要显式检查。

1.2 需要回答的三个问题

  1. 哪里失败了:定位到具体步骤与具体命令。
  2. 失败后发生了什么:脚本是可重入的还是会留下中间状态。
  3. 如何复现:是否有足够上下文(参数、环境、输入)支持重放。

脚本工程的核心就是把这三个问题在编写阶段解决,而不是留到故障现场。

1.3 取舍

选择 获得 付出
严格模式加显式校验 失败快速暴露、行为可预期 需要处理严格模式带来的边界情况
依赖默认行为 写法简洁 上述三种失败形态不可避免地出现

二、原理

2.1 退出码与失败传播

每个命令结束都会返回退出码,0 表示成功,非 0 表示失败。失败传播有三种方式:

方式 写法 特点
立即中止 严格模式或显式判断 失败即停,适合不允许部分完成的任务
收集失败 记录状态并继续 适合批量任务,最后统一汇总
重试后中止 有限次重试后退出 适合存在瞬时故障的外部调用

选择依据是任务是否可安全中断:修改配置、迁移数据这类任务应"失败即停";检查与采集类任务应"收集失败并汇总"。

2.2 严格模式的三个选项

选项 作用 需要注意
出错即退出 命令返回非 0 时立即退出 在多种上下文中失效,见下表
未定义变量报错 引用未设置的变量时中止 与显式默认值写法配合使用
管道整体失败 管道中间任一命令失败则整体失败 未开启时只看最后一个命令的退出码

出错即退出的失效场景是严格模式最需要掌握的部分:

场景 是否生效 说明
作为条件判断的一部分 不生效 条件中的失败由条件自己处理
作为逻辑连接的一环 不生效 左侧失败会被逻辑运算接管
命令前有取反 不生效 退出码被反转,语义已改变
管道中非最后一段 不生效 需要开启管道整体失败选项
子进程或子 shell 内部 不生效 选项不自动下传,需要在子进程内单独设置
命令替换中 视写法而定 部分实现在赋值语句中不生效,需要显式判断

由此产生两条实践结论:

  • 严格模式是"减少遗漏"而不是"保证安全",关键步骤仍需显式判断退出码。
  • 需要严格模式在子进程生效时,应在子脚本与子 shell 中重新设置。

2.3 钩子的分工

钩子 触发条件 用途
退出钩子 脚本以任何方式结束 清理临时资源、释放锁、输出汇总
错误钩子 命令失败时 输出失败上下文(行号、命令、参数)
信号捕获 收到指定信号 优雅停止子进程后退出

错误钩子默认不继承到函数内部,需要开启继承选项(set -E)或在函数内另行设置。三个钩子的具体实现见 作业控制与信号。

2.4 输出规范

输出 去向 用途
业务数据 标准输出 供管道或调用方读取
诊断信息、日志、进度 标准错误 不污染数据通道
# 数据与诊断分离:数据可被管道消费,日志仍可见
list_instances() {
    printf '%s\n' "${instances[@]}"            # 数据走标准输出
}

log_info()  { printf '[%s] [INFO]  %s\n'  "$(date '+%F %T')" "$*" >&2; }
log_warn()  { printf '[%s] [WARN]  %s\n'  "$(date '+%F %T')" "$*" >&2; }
log_error() { printf '[%s] [ERROR] %s\n'  "$(date '+%F %T')" "$*" >&2; }

# 用法:数据与日志互不干扰
instances=$(list_instances)
log_info "共获取 ${#instances[@]} 个实例"

日志格式应固定,包含时间、级别与关键标识(如目标、批次),便于集中检索;日志级别与集中采集的配合见 日志查询与审计 与 监控与告警。

2.5 幂等与文件锁

幂等指"重复执行结果一致"。实现手段是执行前检测当前状态:

场景 检测方式
创建目录 存在则跳过
创建用户与组 查询是否存在后再创建
修改配置 检测目标内容是否已符合预期
部署文件 比对校验和而非只看文件是否存在

需要保证同一时刻只有一个实例运行时使用文件锁:

# 基于文件描述符加锁:脚本退出时锁自动释放,避免残留
readonly LOCK_FILE="/var/lock/app-sync.lock"
exec 9>"$LOCK_FILE"
if ! flock -n 9; then
    log_error "已有实例在运行,退出"
    exit 1
fi

要点:使用文件描述符方式加锁时,锁随进程退出自动释放,不会因脚本异常终止而残留。若使用创建锁文件的方式,则必须在退出钩子中删除,并处理"进程已死但锁文件仍在"的残留情况。

2.6 临时文件与清理

# 安全创建临时目录:名称随机、权限受限
umask 077
tmp_dir="$(mktemp -d -t app-XXXXXX)" || exit 3
trap 'rm -rf -- "$tmp_dir"' EXIT

# 临时文件也应使用随机名称,避免被预测后抢先创建
tmp_file="$(mktemp "${tmp_dir}/result.XXXXXX")"

三条安全要求:

  • 临时文件必须使用随机名称创建,固定名称存在被其他用户抢先创建并借此写入的风险。
  • 权限应限制为仅属主可读写,通过设置权限掩码或使用权限受限的目录实现。
  • 必须在退出钩子中清理,异常退出时也不留下残留。

2.7 安全要点

要点 风险 做法
命令注入 变量内容被当作命令执行 不拼接命令字符串,不将外部输入交给解释器执行
通配符误伤 变量中的通配字符被展开 引用变量,必要时临时关闭通配
选项注入 输入以减号开头被当作选项 命令中显式使用选项终止符
凭据外泄 口令出现在进程列表与日志中 通过环境变量或受限权限的文件传递,不写入日志
权限过高 脚本以高权限运行且可被普通用户修改 脚本与配置目录归属高权限用户且不可写
路径依赖 依赖调用时的当前目录 基于脚本所在目录推导资源路径
环境不可信 继承的路径与变量被篡改 使用绝对路径调用关键命令,必要时重置搜索路径
不可逆操作 删除与覆盖无确认 先打印待处理清单,确认后再执行
# 路径处理:基于脚本所在目录推导,避免依赖当前目录
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
readonly script_dir

# 选项终止符:避免以减号开头的输入被当作选项
rm -f -- "$target"
grep -e "$pattern" file.txt

# 关键命令使用绝对路径,避免被篡改的搜索路径劫持
/usr/bin/install -m 0640 -- "$src" "$dst"

2.8 调试手段

手段 用法 用途
语法检查 解释器带语法检查选项执行 不实际运行即可发现语法错误
执行跟踪 开启跟踪选项 观察每条命令展开后的实际内容
自定义跟踪前缀 设置跟踪提示串包含文件与行号 快速定位到触发点
静态检查 使用专门的静态检查工具 发现引用与比较与未使用变量等常见缺陷
单元化的临时代码 把可疑片段单独放入临时脚本运行 排除环境影响
# 语法检查(重定向用于抑制纯语法检查时的语法错误提示之外的输出)
bash -n script.sh

# 执行跟踪:设置提示串包含脚本名与行号
PS4='+ ${BASH_SOURCE:-$0}:${LINENO}: '
set -x
critical_step
set +x

# 只跟踪指定区段:在函数内部单独开启与关闭
debug_run() { set -x; "$@"; set +x; }
debug_run critical_step

# 跟踪输出重定向到文件,避免与业务输出混在一起
exec 5> /tmp/trace.log
BASH_XTRACEFD=5
set -x
# 静态检查(装入后即可使用)
shellcheck -S warning script.sh
shellcheck -f gcc script.sh | head -20

2.9 可移植性

差异点 说明 建议
默认解释器 部分发行版的默认解释器是精简实现,不支持扩展语法 需要扩展语法时在首行显式声明 bash
双方括号 非标准语法 需要兼容时改用单方括号并严格引用
数组与关联数组 非标准语法 兼容场景改用普通变量与分隔符
字符串大小写转换与替换 参数展开的扩展形式 兼容场景改用外部工具
命令选项 部分选项是特定实现扩展 脚本中避免使用平台专有选项
echo 行为 对转义字符的处理在不同实现中不同 输出使用格式化打印而非 echo

判断标准是"脚本可能运行在哪些系统上":只在受控服务器上运行且明确有 bash 时,可自由使用扩展语法;需要分发给不确定环境或作为系统初始化脚本时,应限制在最小可用语法子集。

三、实现

3.1 完整脚本骨架

#!/usr/bin/env bash
# 说明:同步指定目录到备份位置
# 退出码:0 成功 2 用法错误 3 环境不满足 4 依赖执行失败
set -Eeuo pipefail

# ---------- 基础路径 ----------
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
readonly script_dir
readonly script_name="$(basename -- "${BASH_SOURCE[0]}")"

# ---------- 常量 ----------
readonly LOCK_FILE="/var/lock/${script_name%.sh}.lock"
readonly DATE_TAG="$(date '+%F')"
readonly LOG_DIR="/var/log/app"

umask 077
mkdir -p -- "$LOG_DIR"
readonly LOG_FILE="${LOG_DIR}/${script_name%.sh}.log"

# ---------- 日志 ----------
log() {
    local level="$1"; shift
    printf '[%s] [%s] %s\n' "$(date '+%F %T')" "$level" "$*" | tee -a "$LOG_FILE" >&2
}
log_info()  { log INFO  "$@"; }
log_error() { log ERROR "$@"; }

# ---------- 错误钩子 ----------
# 取退出码必须是函数内第一条语句,之后任何命令都会覆盖它
# set -E 使该陷阱在函数内部同样生效
on_error() {
    local code=$?
    local line="$1" cmd="$2"
    log_error "第 ${line} 行执行失败,退出码=${code},命令=${cmd}"
    exit "$code"
}
trap 'on_error "$LINENO" "$BASH_COMMAND"' ERR

# ---------- 清理钩子 ----------
tmp_dir=""
cleanup() {
    local code=$?
    [[ -n "$tmp_dir" && -d "$tmp_dir" ]] && rm -rf -- "$tmp_dir"
    exit "$code"
}
trap cleanup EXIT

# ---------- 用法 ----------
usage() {
    cat >&2 <<EOF
用法:${script_name} -s <源目录> [-d <目标目录>] [-k <保留天数>]
退出码:0 成功  2 用法错误  3 环境不满足  4 依赖执行失败
EOF
}

# ---------- 参数解析 ----------
src_dir=""
dst_dir="/data/backup"
keep_days=7

while getopts ":s:d:k:h" opt; do
    case "$opt" in
        s) src_dir="$OPTARG" ;;
        d) dst_dir="$OPTARG" ;;
        k) keep_days="$OPTARG" ;;
        h) usage; exit 0 ;;
        :) log_error "选项 -${OPTARG} 缺少参数"; usage; exit 2 ;;
        \?) log_error "未知选项 -${OPTARG}"; usage; exit 2 ;;
    esac
done

[[ -n "$src_dir" ]] || { log_error "缺少必填参数 -s"; usage; exit 2; }
[[ "$keep_days" =~ ^[0-9]+$ ]] || { log_error "保留天数必须为非负整数"; exit 2; }

# ---------- 环境检查 ----------
require_cmd() {
    command -v "$1" >/dev/null 2>&1 || { log_error "缺少命令:$1"; exit 3; }
}
require_cmd rsync
require_cmd find

[[ -d "$src_dir" ]] || { log_error "源目录不存在:$src_dir"; exit 3; }

# ---------- 单实例控制 ----------
exec 9>"$LOCK_FILE"
flock -n 9 || { log_error "已有实例在运行"; exit 1; }

# ---------- 主流程 ----------
main() {
    tmp_dir="$(mktemp -d -t backup-XXXXXX)"

    log_info "开始同步:源=${src_dir} 目标=${dst_dir}"
    rsync -a --delete --exclude='*.tmp' -- "$src_dir"/ "${dst_dir}/${DATE_TAG}/" \
        || { log_error "同步失败"; exit 4; }

    log_info "清理 ${keep_days} 天前的备份"
    find "$dst_dir" -maxdepth 1 -type d -mtime "+${keep_days}" -print \
        | while IFS= read -r old; do
            log_info "删除 ${old}"
            rm -rf -- "$old" || { log_error "删除失败:${old}"; exit 4; }
        done

    log_info "执行完成"
}

main "$@"

要点:错误钩子输出行号与失败命令,退出钩子负责清理,锁使用文件描述符方式,日志同时写入文件与标准错误,退出码按含义分层。

3.2 幂等操作示例

# 创建用户:存在则跳过,避免重复执行报错
ensure_user() {
    local user="$1"
    if id "$user" >/dev/null 2>&1; then
        log_info "用户已存在:${user}"
        return 0
    fi
    useradd --system --no-create-home --shell /usr/sbin/nologin "$user"
}

# 修改配置:内容已符合预期则不动,避免无意义的重启
ensure_line() {
    local file="$1" line="$2"
    grep -qxF -- "$line" "$file" && return 0
    printf '%s\n' "$line" >> "$file"
    log_info "已追加配置:${line}"
}

# 部署文件:比对校验和而非仅判断存在
deploy_if_changed() {
    local src="$1" dst="$2"
    if [[ -f "$dst" ]] && cmp -s -- "$src" "$dst"; then
        log_info "内容一致,跳过:${dst}"
        return 0
    fi
    install -m 0640 -- "$src" "$dst"
    log_info "已更新:${dst}"
}

3.3 安全检查清单

核对项 要求
解释器声明 首行显式声明解释器,需要扩展语法时声明 bash
严格模式 已启用三个选项,关键步骤另有显式判断
变量引用 除明确需要分词外均加双引号
外部输入 已校验类型与范围,未交给解释器执行
路径处理 基于脚本目录推导,关键命令使用绝对路径
选项终止 处理用户输入的路径时使用选项终止符
临时资源 随机名称创建、权限受限、退出时清理
单实例 使用文件锁或进程号文件保证唯一
凭据 不出现在命令行参数与日志中,文件权限受限
不可逆操作 先打印清单再执行,必要时要求确认
幂等 重复执行结果一致,已覆盖中断后重跑
日志 格式固定,含时间与级别,数据与诊断分离
退出码 按含义分层,调用方可区分失败类型
依赖检查 执行前校验必需命令与前置条件

3.4 常见问题对照

现象 常见原因 处置
中间步骤失败但脚本继续执行 未启用严格模式或该上下文使严格模式失效 启用严格模式并对关键步骤显式判断
脚本退出码为 0 但实际失败 失败发生在管道非最后一段 启用管道整体失败选项
日志中出现"命令不存在"但未中止 严格模式在条件上下文中失效 改为显式判断并处理
重复执行导致报错 缺少幂等判断 执行前检测当前状态
出现两个实例同时运行 无单实例控制 使用文件锁
脚本异常终止后无法再次运行 残留锁文件未清理 改用文件描述符方式加锁
临时文件被其他用户读取 权限未限制或名称可预测 限制权限掩码并使用随机名称
密码出现在进程列表中 通过命令行参数传递凭据 改用环境变量或权限受限的文件
从其他目录调用时找不到资源 路径依赖当前目录 基于脚本目录推导
输出被当作数据处理 诊断信息写入了标准输出 日志与诊断统一写入标准错误
语法检查通过但运行报错 语法检查不覆盖运行期错误 结合执行跟踪与静态检查
忘记开启跟踪导致难以定位 缺少调试手段 用环境变量控制跟踪开关,需要时开启

四、总结

  1. 脚本的失败往往是静默的,三种形态(静默继续、部分完成、失败被掩盖)都源于未显式检查退出码。
  2. 脚本工程要在编写阶段回答三个问题:失败位置可定位、失败后可重入、现场可复现。
  3. 严格模式的三个选项能减少遗漏但不能保证安全,出错即退出在条件上下文、逻辑连接、取反、管道非末段与子进程中均会失效。
  4. 退出钩子负责清理、错误钩子负责输出上下文、信号捕获负责优雅停止,三者应指向同一清理逻辑。
  5. 数据走标准输出、诊断走标准错误是脚本可被组合的前提,日志格式应固定并包含时间与级别。
  6. 幂等通过执行前检测状态实现,文件锁通过文件描述符方式实现可避免残留锁导致的无法启动。
  7. 临时资源必须随机命名、权限受限并在退出时清理,固定名称存在被抢先创建的安全风险。
  8. 安全要点集中在命令注入、通配误伤、选项注入、凭据外泄、权限过高与路径依赖六项,均在编码阶段可消除。
  9. 调试的三层手段是语法检查、执行跟踪与静态检查,跟踪应可开关且输出到独立通道。
  10. 可移植性取决于运行环境的确定性,需要分发的脚本应限制在最小语法子集内。