bash-master

Bash 脚本精通

适用范围与平台约定

此技能面向 Bash 本身，适用于 Bash 可运行的所有环境——Linux、macOS、Windows 上的 WSL、Git Bash / MSYS2，以及基于 Bash 的容器映像。不涵盖 原生 PowerShell：PowerShell 脚本属于另一种语言，应使用 powershell-master。在 Windows 上，bash-master 假设用户在 Git Bash、WSL 或类似的 Bash 环境中运行 Bash，并会介绍由此产生的 MSYS 路径转换问题。

仓库约定

项目级约定（工具调用中的 Windows 反斜杠、文档规范等）由 Agent 正文和 windows-path-master 插件负责。此技能专注于 Bash 内容；不要在此重复那些模板内容。

快速参考

#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures
IFS=$'\n\t'        # Safe word splitting
# Run shellcheck your_script.sh before deployment.
# Test on every target platform before production.

Bash 可移植性快速检查：

# Linux/macOS:       Full bash features
# Git Bash (Windows): Most features, some system calls missing (no systemd, /proc differs)
# WSL:               Effectively Linux; /mnt/c for Windows filesystem
# Containers:        Depends on base image - alpine ships /bin/sh, not bash
# POSIX mode:        Use /bin/sh and avoid bashisms

何时使用此技能

始终在以下情况下启用：

• 编写或修改任何 Bash/shell 脚本
• 审查或重构现有脚本
• 调试 shell 脚本故障
• DevOps 自动化、CI/CD 流水线、系统管理
• 跨环境 Bash 可移植性（Linux <-> macOS <-> WSL <-> Git Bash <-> 容器）

以下情况不要使用此技能：

• PowerShell 脚本——使用 powershell-master
• Batch（.cmd/.bat）脚本
• 与脚本编写无关的通用命令帮助

核心原则

1. 安全第一

每个脚本都应以安全前置代码开头：

#!/usr/bin/env bash
set -e            # Exit on any error
set -u            # Exit on undefined variable
set -o pipefail   # Catch failures mid-pipeline
set -E            # Inherit ERR trap into functions
IFS=$'\n\t'       # Avoid word splitting on spaces

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"

2. POSIX 与 Bash

需要在任何 UNIX sh 上运行	#!/bin/sh，不使用 [[ ]]、数组或进程替换
使用 Bash 的现代 Linux/macOS	#!/usr/bin/env bash，优先使用 [[ ]]、数组和正则表达式
Alpine/精简容器	明确安装 bash，或编写符合 POSIX 标准的 sh 脚本

3. 引号

# Always quote expansions
process "$file_path"        # correct
process $file_path          # word-splitting bug

# Arrays
files=("file 1.txt" "file 2.txt")
process "${files[@]}"       # each element kept separate
process "${files[*]}"       # joined as one string - usually wrong

4. ShellCheck

对每个脚本运行 shellcheck。只有在注释中说明理由时，才禁用警告：# shellcheck disable=SC2086 reason: intentional word splitting。

完整的引号/风格表见 references/best_practices.md，常见陷阱见 references/patterns_antipatterns.md。

平台特定注意事项

Git Bash / MSYS2（Windows）

Git Bash 会自动将 Unix 风格的参数转换为 Windows 路径。这是 Windows 上跨平台 Bash 故障的最大单一来源。

# The conversion: /foo becomes C:/Program Files/Git/usr/foo
# Disable per-command:
MSYS_NO_PATHCONV=1 command /path/that/should/stay/unix

# Manual conversion
unix_path=$(cygpath -u "C:\Windows\System32")
win_path=$(cygpath -w "/c/Users/username")

# Detect Git Bash
if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "mingw"* ]]; then
    : # Git Bash
fi
case "${MSYSTEM:-}" in
    MINGW64|MINGW32|MSYS) : ;;  # MSYS2 / Git Bash environment
esac

# Flags that look like paths
command //e //s   # double-slash to suppress conversion
command -e -s     # or use dash-options

完整的 Git Bash 与 Windows 路径说明见 references/windows-git-bash-paths.md。

Linux

GNU coreutils、/proc、systemd 集成。使用 [[ "$OSTYPE" == "linux-gnu"* ]] 检测。

macOS

BSD 工具的行为与 GNU 工具不同。最常见的问题：sed -i ''（必须提供空字符串）、date 标志不同、原生 macOS 未提供 readlink -f。

if command -v gsed >/dev/null; then SED=gsed; else SED=sed; fi

WSL

本质上等同于 Linux。Windows 文件系统挂载在 /mnt/c/。使用 grep -qi microsoft /proc/version 检测。

容器

Alpine 映像仅包含 /bin/sh（BusyBox）。应编写符合 POSIX 标准的脚本，或运行 apk add bash。容器初始化的特殊之处：PID 1 必须回收子进程并处理信号。使用 [ -f /.dockerenv ] 或 [ -n "$KUBERNETES_SERVICE_HOST" ] 检测。

可移植的平台检测模板

detect_platform() {
    case "$OSTYPE" in
        linux-gnu*)    echo "linux" ;;
        darwin*)       echo "macos" ;;
        msys*|cygwin*) echo "windows" ;;
        *)             echo "unknown" ;;
    esac
}

各平台的完整表格（BSD 与 GNU coreutils 标志、WSL 网络、容器初始化模式）见 references/platform_specifics.md。

最佳实践（摘要）

完整的模式——函数设计、错误处理、输入验证、参数解析、日志记录——见 references/in-depth-patterns.md。主要规则：

• 每个函数只处理一个关注点；先声明局部变量；验证输入；出错时返回非零值。
• 常量使用 UPPER_CASE；局部变量使用 lower_case；不可变值标记为 readonly。
• 始终检查退出码（使用 if ! cmd、||、陷阱，或集中式 error_exit 辅助函数）。
• 验证每个外部输入——空值、格式、长度、字符集。
• 使用 getopts 或基于 case 的参数解析器；遇到无效输入时打印用法并以 1 退出。
• 使用分级日志记录器，并将日志写入 stderr。

安全性、性能、测试、调试、高级模式

这些主题在 references/in-depth-patterns.md 中各有专门章节：

主题	涵盖内容
安全性	防止命令注入、路径遍历防护、权限管理、安全临时文件
性能	避免子 shell、Bash 内置命令与外部命令、进程替换、数组操作
测试	BATS 单元测试、集成测试模式、CI/CD 接入
调试	set -x、PS4、条件调试辅助函数、跟踪和性能分析
高级模式	安全解析配置、并行处理、信号处理、退避重试

需要获取这些主题的规范代码模板时，请阅读该参考文档。

参考文件

• references/platform_specifics.md - 详细的平台差异和解决方法
• references/best_practices.md - 全面的行业标准和指南
• references/patterns_antipatterns.md - 常见模式和陷阱及其解决方案
• references/windows-git-bash-paths.md - Git Bash / MSYS 路径转换参考
• references/in-depth-patterns.md - 函数设计、安全性、性能、测试、调试和高级模式
• references/resources.md - 官方文档、风格指南、工具和学习链接

成功标准

使用此技能编写的 Bash 脚本应当：

1. 通过 shellcheck 检查，且没有警告
2. 以 set -euo pipefail 开头
3. 为每个变量展开添加引号
4. 在遇到 -h/--help 时显示用法说明
5. 拆分为可测试的函数
6. 处理空输入、缺失文件和意外参数
7. 能在所有声明支持的目标平台（Linux/macOS/WSL/Git Bash/container）上运行
8. 符合 Google Shell Style Guide
9. 在退出时清理（trap EXIT）
10. 对逻辑不简单的部分使用 BATS 进行单元测试

# Pre-deployment checklist
shellcheck script.sh
bash -n script.sh
bats test/script.bats
./script.sh --help
DEBUG=true ./script.sh

故障排除

脚本在其他平台上运行失败

• 运行 checkbashisms script.sh，找出不可移植的结构。
• 运行 command -v tool，确认所需工具已安装。
• 比较 GNU 和 BSD 命令的标志（例如 sed --version）。

ShellCheck 警告

• 阅读规则说明（shellcheck -W SC2086）。
• 修复根本问题；只有在附上说明注释时，才禁用规则。

在交互式环境中运行正常，但在 cron 中失败

• Cron 的 PATH 很精简——请显式设置 PATH。
• 使用绝对路径。
• 重定向标准输出和标准错误：./script.sh >> /tmp/cron.log 2>&1。

性能问题

• 使用 time 进行性能分析。
• 启用 set -x，找出耗时步骤。
• 尽可能使用 Bash 内置命令替代外部调用。