# Shell 脚本通用要点 适用于所有用 shell 完成的工作：部署和运维脚本、构建脚本、一次性的命令行操作。示例以 bash 为准。 ## 一、动手前 - **先确认目标和流程。** 写下脚本要从什么状态到什么状态、中间有哪些步骤、哪一步之后不能回头。流程有多种做法时，先和使用者确认，从最简单的那种开始。 - **先看一眼要改动的对象。** 删除、覆盖、移动之前，确认目标路径、分支、主机和自己设想的一致。 - **能用现成工具就不自己造。** 优先用系统自带的命令，只有确实需要时才调用应用代码或额外的运行时。 ## 二、失败要安全 - **出错就停。** 开头写 `set -Eeuo pipefail`，再加 `trap 'printf "第 %s 行失败（退出码 %s）\n" "$LINENO" "$?" >&2' ERR`，失败时能看到是哪一行。 - **操作要可逆，影响范围要小。** 改名保留，少用删除。改动前先备份，备份放在脚本固定管理的位置。`rm -rf --` 只用于脚本自己创建、路径固定的目录，路径绝不能来自可能为空的变量。 - **半途失败要回到能用的状态。** 在改动线上状态之前注册 `trap ... EXIT`，用来撤回改动或恢复旧服务。到达“不能自动撤回”的那一步时，用 `trap - EXIT` 取消。 - **不能自动撤回的失败，给出下一步命令。** 例如“启动失败，执行 `bash xxx rollback`”。会丢数据的恢复由人决定，不自动执行。 - **可以重复执行。** 第二次运行不会破坏第一次的结果：已经完成的步骤要么跳过，要么明确拒绝并说明原因。 ## 三、检查要准 - **检查的必须是真正关心的东西。** “接口返回 200”比“进程存在”更能说明服务可用，“读得到数据库的接口返回 200”又比“首页返回 200”更可靠。 - **在不会变化的数据上做严格比对。** 比对前后状态时，先让数据停止变化（停服务、取快照），再要求完全相等。不要在一直变化的数据上设容忍规则。 - **不写死只对一次运行成立的值。** 具体的版本号、行数、条目数、文件内容标记，下一次运行就会误报。 - **有差异就列出明细。** 打印“前 → 后”，再由人确认。不确定时默认取消。 - **能自动查到的事实，不让人回答。** 只有判断本身需要人来做时才询问。 ## 四、交互 - **确认词按后果分级。** 只是提醒、可以继续的用 `y`；停机、删除、改数据用 `yes`。不提供跳过所有确认的开关。 - **非交互时默认取消。** `read -r -p '…' answer || true`，空答案当作取消。 - **输出分层。** 步骤、警告、错误各用固定的前缀；警告和错误写到 stderr；错误以非零状态退出。每一步结束时告诉使用者下一步做什么。 - **不打印凭据。** 密码、令牌、私钥、Cookie 不出现在输出、日志和命令行参数里，需要时引用文件路径。 ## 五、写法 - **常量放在顶部。** 路径、服务名、端口写成大写常量。函数里的变量用 `local`。 - **只调用一次的逻辑直接内联。** 被多处调用的才写成函数。不要为了“看起来整齐”拆出只用一次的小函数。 - **子命令少而完整。** 每个子命令完成一件完整的事。不带参数时打印用法，并以 2 退出。 - **依赖在入口处检查。** 用 `command -v` 检查要用的命令，缺少时直接告诉使用者怎么安装，不要等到中途才失败。 - **注释只写原因。** 代码已经说明了在做什么，注释解释为什么这样做。 - **变量一律加引号。** `"$var"`、`"${arr[@]}"`。路径参数前加 `--`，防止以 `-` 开头的值被当成选项。 ## 六、常见陷阱 - **`&&`、`||` 链里的失败不会触发 `set -e`。** 必须失败即停的链写成 `a && b || die '原因'`。 - **`local x=$(cmd)` 会吞掉退出码。** 先写 `local x`，再写 `x=$(cmd)`。 - **命令替换直接作为参数时，失败不会让脚本停下。** 例如 `tool "$(生成参数)"`。先赋给变量，再使用。 - **`pipefail` 下，`cmd | grep -q` 可能因为 SIGPIPE 得到错误的退出码。** 先 `out=$(cmd)`，再用 `case` 或 `grep` 处理这个变量。 - **函数或循环的最后一行是 `[ 条件 ] && 动作` 时，条件为假会让返回值非零。** 改用 `if`。 - **通配符没有匹配时会原样保留。** 使用前先用 `[ -e ]` 判断，或者开启 `nullglob`。 - **相对路径依赖当前目录。** 给函数和外部命令传完整路径。很多工具遇到不存在的路径会默默新建，例如 sqlite3 会新建一个空库，检查反而“通过”。 - **`cd` 会影响后面的所有命令。** 需要时放进子 shell：`(cd dir && cmd)`。 - **`sudo cmd > file` 的重定向不在 sudo 里执行。** 改用 `cmd | sudo tee file`。 - **`printf '%-10s'` 按字节计算宽度。** 中文等多字节字符会对不齐，改用“名称：值”的格式。 - **heredoc 是否展开变量取决于结束标记的引号。** `<<'EOF'` 不展开，`<