shellcheck

Shellcheck

检查 shell 脚本（.sh、bash、sh、dash、ksh）中的语法错误、常见错误、引号问题和可移植性问题。捕获那些原本只有在运行时才会出现的错误。

此技能的功能

1. 检查是否已安装 shellcheck；如果未安装，则指导安装。
2. 检测项目特定的 .shellcheckrc，否则使用合理的默认配置。
3. 检查 shell 脚本中的语法、引号、安全性、可移植性和最佳实践问题。
4. 报告错误，提供具体的 SC 代码和修复方法。

安装检查

shellcheck --version 2>/dev/null

如果未安装，请使用以下任一方式安装：

# Debian/Ubuntu
sudo apt-get install shellcheck

# Homebrew (macOS/Linux)
brew install shellcheck

# Snap
sudo snap install shellcheck

# Download binary (Linux amd64)
curl -sL "$(curl -sL https://api.github.com/repos/koalaman/shellcheck/releases/latest \
  | grep browser_download_url | grep linux.x86_64.tar.xz | cut -d'"' -f4)" \
  | tar xJ -C /usr/local/bin shellcheck

如果安装失败，请停止并报告问题及解决步骤。不要悄悄跳过检查。

配置检测优先级

1. 项目根目录中的 .shellcheckrc
2. 主目录中的 ~/.shellcheckrc
3. $XDG_CONFIG_HOME/shellcheckrc（如果已设置 XDG_CONFIG_HOME）
4. 默认配置（参见 references/shellcheckrc）

如果不存在项目配置，请先使用 references 中的默认配置，再运行检查。

检查工作流

1. Check shellcheck installation
   ├─ Installed → continue
   └─ Missing → install, then continue (fail if install fails)

2. Detect project config
   ├─ Found → use it
   └─ Not found → use default config from references/

3. Run validation
   ├─ All scripts:
   │    find . -name '*.sh' -exec shellcheck {} +
   ├─ Specific files:
   │    shellcheck script.sh deploy.sh
   └─ With explicit shell:
        shellcheck -s bash script.sh

4. Report results
   ├─ Valid → confirm and proceed
   └─ Invalid → show errors, suggest fixes, re-validate after correction

检查方法

检查所有 shell 脚本（自动发现 *.sh）

find . -name '*.sh' -exec shellcheck {} +

检查指定文件

shellcheck script.sh deploy.sh

使用明确的 shell 方言进行检查

shellcheck -s bash script.sh
shellcheck -s sh script
shellcheck -s dash dash-script

从标准输入检查（适用于生成的脚本）

cat script.sh | shellcheck -

按严重程度筛选

# Warnings and above
shellcheck --severity=warning script.sh

# Errors only
shellcheck --severity=error script.sh

# Info and above (verbose)
shellcheck --severity=info script.sh

错误处理

安装失败

如果无法安装 shellcheck，请报告错误并提供解决步骤。不要继续检查。

检查失败

检查失败时，请针对每个错误报告以下信息：

• 文件和行号
• SC 代码（例如 SC2086）
• 严重程度（错误、警告、信息、风格）
• 问题所在
• 具体修复方法

示例：

Validation failed:

1. script.sh:5:3 SC2086 (info): Double quote to prevent globbing
   Bad:   echo $USER logged in at $HOME
   Fix:   echo "$USER logged in at $HOME"

2. script.sh:12:1 SC2164 (warning): Use 'cd ... || exit' in case cd fails
   Bad:   cd /app
   Fix:   cd /app || exit 1

3. script.sh:15:20 SC2155 (warning): Declare and assign separately
   Bad:   local result=$(whoami)
   Fix:   local result; result=$(whoami)

4. script.sh:18:1 SC2012 (info): Use find instead of ls in loops
   Bad:   for f in $(ls *.txt); do
   Fix:   for f in *.txt; do

报告错误后，建议修复方法，并在修正后重新检查。

规则参考

完整的规则参考、常见错误类别、SC 代码说明和详细修复示例，请参阅 references/shellcheck-rules.md。