名称：shellcheck配置描述：掌握ShellCheck静态分析配置和使用，以提升shell脚本质量。在设置linting基础设施、修复代码问题或确保脚本可移植性时使用。

ShellCheck配置与静态分析

全面的指导，用于配置和使用ShellCheck以提高shell脚本质量、捕捉常见陷阱，并通过静态代码分析强制执行最佳实践。

何时使用此技能

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

ShellCheck基础

什么是ShellCheck？

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

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

安装

# 使用Homebrew在macOS上安装
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：此词非标准。设置POSIXLY_CORRECT
# 当与其他shell的脚本使用时

SC2100-2199：引用问题

# SC2086：双引号以防止通配和词分割
for i in $list; do  # 应为：for i in $list 或 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 )  # 应使用：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 "检查: $script"
    shellcheck \
        --shell=bash \
        --format=gcc \
        --exclude=SC1091 \
        "$script" || exit 1
done

项目级的.shellcheckrc

# 要分析的目标shell方言
shell=bash

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

# 禁用特定警告
# SC1091：不跟踪源文件（许多误报）
disable=SC1091

# SC2119：使用function_name代替function_name --（参数）
disable=SC2119

# 外部文件源以提供上下文
external-sources=true

集成模式

预提交钩配置

#!/bin/bash
# .git/hooks/pre-commit

#!/bin/bash
set -e

# 查找此提交中更改的所有shell脚本
git diff --cached --name-only | grep '\.sh$' | while read -r script; do
    echo "Linting: $script"

    if ! shellcheck "$script"; then
        echo "ShellCheck 在 $script 上失败"
        exit 1
    fi
done

GitHub Actions工作流

name: ShellCheck

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: 运行 ShellCheck
        run: |
          sudo apt-get install shellcheck
          find . -type f -name "*.sh" -exec shellcheck {} \;

GitLab CI流水线

shellcheck:
  stage: lint
  image: koalaman/shellcheck-alpine
  script:
    - find . -type f -name "*.sh" -exec shellcheck {} \;
  allow_failure: false

处理ShellCheck违规

抑制特定警告

#!/bin/bash

# 为整行禁用警告
# shellcheck disable=SC2086
for file in $(ls -la); do
    echo "$file"
done

# 为整个脚本禁用
# shellcheck disable=SC1091,SC2119

# 禁用多个警告（格式可变）
command_that_fails() {
    # shellcheck disable=SC2015
    [ -f "$1" ] && echo "found" || echo "not found"
}

# 为源指令禁用特定检查
# shellcheck source=./helper.sh
source helper.sh

常见违规与修复

SC2086：双引号以防止词分割

# 问题
for i in $list; do done

# 解决方案
for i in $list; do done  # 如果$list已引用，或
for i in "${list[@]}"; do done  # 如果list是数组

SC2181：直接检查退出代码

# 问题
some_command
if [ $? -eq 0 ]; then
    echo "success"
fi

# 解决方案
if some_command; then
    echo "success"
fi

SC2015：使用if-then代替 && ||

# 问题
[ -f "$file" ] && echo "exists" || echo "not found"

# 解决方案 - 意图更清晰
if [ -f "$file" ]; then
    echo "exists"
else
    echo "not found"
fi

SC2016：表达式在单引号中不展开

# 问题
echo 'Variable value: $VAR'

# 解决方案
echo "Variable value: $VAR"

SC2009：使用pgrep代替grep

# 问题
ps aux | grep -v grep | grep myprocess

# 解决方案
pgrep -f myprocess

性能优化

检查多个文件

#!/bin/bash

# 顺序检查
for script in *.sh; do
    shellcheck "$script"
done

# 并行检查（更快）
find . -name "*.sh" -print0 | \
    xargs -0 -P 4 -n 1 shellcheck

缓存结果

#!/bin/bash

CACHE_DIR=".shellcheck_cache"
mkdir -p "$CACHE_DIR"

check_script() {
    local script="$1"
    local hash
    local cache_file

    hash=$(sha256sum "$script" | cut -d' ' -f1)
    cache_file="$CACHE_DIR/$hash"

    if [[ ! -f "$cache_file" ]]; then
        if shellcheck "$script" > "$cache_file" 2>&1; then
            touch "$cache_file.ok"
        else
            return 1
        fi
    fi

    [[ -f "$cache_file.ok" ]]
}

find . -name "*.sh" | while read -r script; do
    check_script "$script" || exit 1
done

输出格式

默认格式

shellcheck script.sh

# 输出：
# script.sh:1:3: warning: foo is referenced but not assigned. [SC2154]

GCC格式（用于CI/CD）

shellcheck --format=gcc script.sh

# 输出：
# script.sh:1:3: warning: foo is referenced but not assigned.

JSON格式（用于解析）

shellcheck --format=json script.sh

# 输出：
# [{"file": "script.sh", "line": 1, "column": 3, "level": "warning", "code": 2154, "message": "..."}]

安静格式

shellcheck --format=quiet script.sh

# 如果发现问题返回非零值，否则无输出

最佳实践

在CI/CD中运行ShellCheck - 在合并前捕捉问题
为你的目标shell配置 - 不要将bash分析为sh
记录排除项 - 解释为什么抑制违规
处理违规 - 不要仅禁用警告
启用严格模式 - 使用--enable=all并谨慎排除
定期更新 - 保持ShellCheck当前以获取新检查
使用预提交钩 - 在推送前本地捕捉问题
与编辑器集成 - 在开发时获取实时反馈

资源

ShellCheck GitHub：https://github.com/koalaman/shellcheck
ShellCheck Wiki：https://www.shellcheck.net/wiki/
错误代码参考：https://www.shellcheck.net/

名称：shellcheck配置 描述：掌握ShellCheck静态分析配置和使用，以提升shell脚本质量。在设置linting基础设施、修复代码问题或确保脚本可移植性时使用。

ShellCheck配置与静态分析

何时使用此技能

ShellCheck基础

什么是ShellCheck？

安装

配置文件

.shellcheckrc（项目级别）

环境变量

常见ShellCheck错误代码

SC1000-1099：解析器错误

SC2000-2099：Shell问题

SC2100-2199：引用问题

SC3000-3999：POSIX兼容性问题

实际配置示例

最小配置（严格POSIX）

开发配置（Bash，规则较宽松）

CI/CD集成配置

项目级的.shellcheckrc

集成模式

预提交钩配置

GitHub Actions工作流

GitLab CI流水线

处理ShellCheck违规

抑制特定警告

常见违规与修复

SC2086：双引号以防止词分割

SC2181：直接检查退出代码

SC2015：使用if-then代替 && ||

SC2016：表达式在单引号中不展开

SC2009：使用pgrep代替grep

性能优化

检查多个文件

缓存结果

输出格式

默认格式

GCC格式（用于CI/CD）

JSON格式（用于解析）

安静格式

最佳实践

资源

名称：shellcheck配置描述：掌握ShellCheck静态分析配置和使用，以提升shell脚本质量。在设置linting基础设施、修复代码问题或确保脚本可移植性时使用。