---

name: shellcheck-configuration description: "掌握 ShellCheck 静态分析配置和使用，提升 Shell 脚本质量。在设置 lint 基础设施、修复代码问题或确保脚本可移植性时使用。" risk: unknown source: community date_added: "2026-02-27"

ShellCheck 配置与静态分析

全面指导如何配置和使用 ShellCheck 来提升 Shell 脚本质量、捕获常见陷阱，并通过静态代码分析强制执行最佳实践。

不适用场景

• 任务与 ShellCheck 配置和静态分析无关
• 需要此范围之外的其他领域或工具

使用说明

• 明确目标、约束条件和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可操作的步骤和验证方法。
• 如需详细示例，请打开 resources/implementation-playbook.md。

适用场景

• 在 CI/CD 流水线中为 Shell 脚本设置 lint
• 分析现有 Shell 脚本的问题
• 理解 ShellCheck 错误代码和警告
• 为特定项目需求配置 ShellCheck
• 将 ShellCheck 集成到开发工作流中
• 抑制误报和配置规则集
• 强制执行一致的代码质量标准
• 迁移脚本以满足质量门禁

ShellCheck 基础

什么是 ShellCheck？

ShellCheck 是一个静态分析工具，用于分析 Shell 脚本并检测有问题的模式。它支持：

• Bash、sh、dash、ksh 和其他 POSIX shell
• 超过 100 种不同的警告和错误
• 目标 shell 和标志的配置
• 与编辑器和 CI/CD 系统的集成

安装

# macOS 使用 Homebrew
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# 从源码编译
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
make build
make install

# 验证安装
shellcheck --version

配置文件

.shellcheckrc（项目级别）

在项目根目录创建 .shellcheckrc：

# 指定目标 shell
shell=bash

# 启用可选检查
enable=avoid-nullary-conditions
enable=require-variable-braces

# 禁用特定警告
disable=SC1091
disable=SC2086

环境变量

# 设置默认 shell 目标
export SHELLCHECK_SHELL=bash

# 启用严格模式
export SHELLCHECK_STRICT=true

# 指定配置文件位置
export SHELLCHECK_CONFIG=~/.shellcheckrc

常见 ShellCheck 错误代码

SC1000-1099：解析器错误

# SC1004: 反斜杠续行后没有换行符
echo hello\
world  # 错误 - 需要行续接

# SC1008: 操作符 '==' 的数据无效
if [[ $var =  "value" ]]; then  # == 前有空格
    true
fi

SC2000-2099：Shell 问题

# SC2009: 考虑使用 pgrep 或 pidof 代替 grep|grep
ps aux | grep -v grep | grep myprocess  # 改用 pgrep

# SC2012: 仅用 ls 查看。使用 find 获取可靠输出
for file in $(ls -la)  # 更好：使用 find 或通配符

# SC2015: 避免使用 && 和 || 代替 if-then-else
[[ -f "$file" ]] && echo "found" || echo "not found"  # 不够清晰

# SC2016: 表达式在单引号中不会展开
echo '$VAR'  # 字面量 $VAR，不是变量展开

# SC2026: 此词非标准。使用其他 shell 脚本时设置 POSIXLY_CORRECT

SC2100-2199：引号问题

# SC2086: 双引号以防止通配符展开和词分割
for i in $list; do  # 应该是：for i in "$list"
    echo "$i"
done

# SC2115: 路径中的字面波浪号不会展开。改用 $HOME
~/.bashrc  # 在字符串中使用 "$HOME/.bashrc"

# SC2181: 直接用 if 检查退出码，不要间接在列表中检查
some_command
if [ $? -eq 0 ]; then  # 更好：if some_command; then

# SC2206: 引用以防止词分割或设置 IFS
array=( $items )  # 应该引用

SC3000-3999：POSIX 合规问题

# SC3010: 在 POSIX sh 中，使用 'case' 代替 'cond && foo'
[[ $var == "value" ]] && do_something  # 非 POSIX

# SC3043: 在 POSIX sh 中，'local' 未定义
function my_func() {
    local var=value  # 在某些 shell 中非 POSIX
}

实用配置示例

最小配置（严格 POSIX）

#!/bin/bash
# 配置为最大可移植性

shellcheck \
  --shell=sh \
  --external-sources \
  --check-sourced \
  script.sh

开发配置（Bash 宽松规则）

#!/bin/bash
# 配置为 Bash 开发

shellcheck \
  --shell=bash \
  --exclude=SC1091,SC2119 \
  --enable=all \
  script.sh

CI/CD 集成配置

#!/bin/bash
set -Eeuo pipefail

# 分析所有 shell 脚本，有问题则失败
find . -type f -name "*.sh" | while read -r script; do
    echo "Checking: $script"
    shellcheck \
        --shell=bash \
        --format=gcc \
        --exclude=SC1091 \
        "$script" || exit 1
done