5.1.2 脚本结构与注释规范

脚本结构与注释规范是保证可读性、可维护性与可协作性的基础。本节从脚本骨架、注释类型、头部信息、命令与调试示例、排错与练习进行说明，并给出可执行示例。

脚本基本结构#

一个规范的 Shell 脚本通常由以下部分组成：
1. Shebang：指定解释器
2. 脚本头部注释：用途、作者、版本、更新时间
3. 变量与函数定义区
4. 主逻辑入口
5. 退出状态与清理

结构示意图（流程清晰，便于快速定位问题）：

文章图片

注释类型与规范#

  • 头部注释：脚本元信息
  • 行内注释：对关键命令或参数解释
  • 块注释：一段逻辑或函数的说明
  • 禁止滥用注释：注释解释“为什么”，代码表达“做什么”

推荐头部注释模板：

#!/usr/bin/env bash
#===============================================================================
# Name        : backup.sh
# Description : 备份指定目录到 /data/backup
# Author      : ops
# Version     : 1.0.0
# Update      : 2025-01-01
#===============================================================================

完整可执行示例（含注释规范）#

文件路径：/opt/scripts/backup.sh

#!/usr/bin/env bash
#===============================================================================
# Name        : backup.sh
# Description : 备份指定目录到 /data/backup，并保留最近 7 天
# Author      : ops
# Version     : 1.0.0
# Update      : 2025-01-01
# Usage       : ./backup.sh /etc
#===============================================================================

set -euo pipefail  # 遇错退出/未定义变量报错/管道错误可见
IFS=$'\n\t'

SRC_DIR="${1:-/etc}"              # 默认备份 /etc
BACKUP_DIR="/data/backup"
DATE_TAG="$(date +%F)"
ARCHIVE="${BACKUP_DIR}/backup_${DATE_TAG}.tar.gz"

# 检查依赖命令
command -v tar >/dev/null 2>&1 || { echo "tar not found"; exit 127; }

# 创建备份目录
mkdir -p "${BACKUP_DIR}"

# 备份执行
tar -zcf "${ARCHIVE}" "${SRC_DIR}"  # -z gzip 压缩，-c 创建，-f 指定文件
echo "Backup created: ${ARCHIVE}"

# 清理超过 7 天的备份
find "${BACKUP_DIR}" -name "backup_*.tar.gz" -mtime +7 -type f -print -delete

exit 0

执行与预期效果：

chmod +x /opt/scripts/backup.sh
/opt/scripts/backup.sh /etc
# 预期输出：Backup created: /data/backup/backup_YYYY-MM-DD.tar.gz

关键命令解释#

set -euo pipefail   # -e 出错即退出；-u 未定义变量报错；pipefail 捕获管道错误
tar -zcf file.tar.gz /path  # -z gzip 压缩；-c 创建；-f 指定文件
find /data/backup -mtime +7 -type f -delete  # 删除 7 天前文件

排错与调试#

常见问题与处理：
1. 执行时报 “bad interpreter: /bin/bash^M”
原因：Windows 换行符
处理：
bash dos2unix /opt/scripts/backup.sh
2. 权限不足
处理：
bash chmod +x /opt/scripts/backup.sh ls -l /opt/scripts/backup.sh
3. 路径或变量未定义导致失败
使用调试模式：
bash bash -x /opt/scripts/backup.sh /etc

练习#

  1. 修改脚本：将备份保留天数参数化，默认 7 天。
  2. 增加日志：把所有输出写入 /var/log/backup.log。
  3. 增加失败告警：当 tar 失败时输出明确错误并返回非 0 状态。