
关于
精通 ShellCheck 静态分析配置和 Shell 脚本质量检查。适用于搭建代码检查基础设施、修复代码问题或确保脚本可移植性。
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
兼容工具
Claude CodeCursor
标签
运维部署

