shell-script-debugging.md

domain	contrib
title	Shell Debugging — set -x 与常见Pitfalls
verification	metadata-normalized

---{"title": "Shell Debugging — set -x 与常见Pitfalls", "domain": "development", "tags": ["shell", "bash", "debug", "script"]}---

背景

Shell 脚本报错但不显示问题行，或变量展开后不是预期值。

根因

Shell 默认只输出执行结果，不输出执行过程。变量为空、特殊字符展开、IFS 分割等问题只有看到「实际执行了什么命令」才能发现。

修复

#!/usr/bin/env bash
# Shell Debugging — set -x 与常见Pitfalls
set -x   # 打印执行的命令（+ 前缀）
set -e   # 任何命令失败时退出
set -u   # 使用未定义变量时报错
set -o pipefail  # 管道中任一命令失败也算失败

# 推荐组合：脚本开头加这一行
set -euxo pipefail

# 示例 - 没加 set -x 看不出问题：
FILES=$(ls *.txt | head -5)
for f in $FILES; do  # 如果文件名有空格，会被分割！
    echo "处理: $f"
done

# set -x 后会看到实际展开：
# ++ ls 'file 1.txt' 'file 2.txt'
# + FILES='file 1.txt
# file 2.txt'

Verification

1. Follow the solution steps in order
2. Run any relevant commands or tests to confirm the fix
3. Verify the symptom no longer occurs
4. Check related logs or outputs for expected behavior

陷阱

场景	问题	修复
文件名含空格	for f in $FILES 按空格分割	for f in "$FILES" 或 find -print0
变量未定义	变成空字符串	set -u 捕获
ls 结果赋值	带换行符	用 mapfile 或 find
管道静默失败	前一个命令失败但 `	` 忽略