鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

shellcheck-configuration

提供 ShellCheck 静态分析能力,支持针对不同 shell 环境的脚本质量检查、常见错误识别与修复建议,可配置规则集、抑制误报,并集成到开发流程和 CI/CD 系统中,保障脚本可靠性、可移植性与安全性。

测试与安全效率工具
访问 GitHub
文档Skills.MD
name
shellcheck-configuration
description
Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.

ShellCheck Configuration and Static Analysis

Comprehensive guidance for configuring and using ShellCheck to improve shell script quality, catch common pitfalls, and enforce best practices through static code analysis.

When to Use This Skill

  • Setting up linting for shell scripts in CI/CD pipelines
  • Analyzing existing shell scripts for issues
  • Understanding ShellCheck error codes and warnings
  • Configuring ShellCheck for specific project requirements
  • Integrating ShellCheck into development workflows
  • Suppressing false positives and configuring rule sets
  • Enforcing consistent code quality standards
  • Migrating scripts to meet quality gates

ShellCheck Fundamentals

What is ShellCheck?

ShellCheck is a static analysis tool that analyzes shell scripts and detects problematic patterns. It supports:

  • Bash, sh, dash, ksh, and other POSIX shells
  • Over 100 different warnings and errors
  • Configuration for target shell and flags
  • Integration with editors and CI/CD systems

Installation

▼
bash
复制代码
# macOS with Homebrew brew install shellcheck # Ubuntu/Debian apt-get install shellcheck # From source git clone https://github.com/koalaman/shellcheck.git cd shellcheck make build make install # Verify installation shellcheck --version

Configuration Files

.shellcheckrc (Project Level)

Create .shellcheckrc in your project root:

▼
text
复制代码
# Specify target shell shell=bash # Enable optional checks enable=avoid-nullary-conditions enable=require-variable-braces # Disable specific warnings disable=SC1091 disable=SC2086

Environment Variables

▼
bash
复制代码
# Set default shell target export SHELLCHECK_SHELL=bash # Enable strict mode export SHELLCHECK_STRICT=true # Specify configuration file location export SHELLCHECK_CONFIG=~/.shellcheckrc

Common ShellCheck Error Codes

SC1000-1099: Parser Errors

▼
bash
复制代码
# SC1004: Backslash continuation not followed by newline echo hello\ world # Error - needs line continuation # SC1008: Invalid data for operator `==' if [[ $var = "value" ]]; then # Space before == true fi

SC2000-2099: Shell Issues

▼
bash
复制代码
# SC2009: Consider using pgrep or pidof instead of grep|grep ps aux | grep -v grep | grep myprocess # Use pgrep instead # SC2012: Use `ls` only for viewing. Use `find` for reliable output for file in $(ls -la) # Better: use find or globbing # SC2015: Avoid using && and || instead of if-then-else [[ -f "$file" ]] && echo "found" || echo "not found" # Less clear # SC2016: Expressions don't expand in single quotes echo '$VAR' # Literal $VAR, not variable expansion # SC2026: This word is non-standard. Set POSIXLY_CORRECT # when using with scripts for other shells

SC2100-2199: Quoting Issues

▼
bash
复制代码
# SC2086: Double quote to prevent globbing and word splitting for i in $list; do # Should be: for i in $list or for i in "$list" echo "$i" done # SC2115: Literal tilde in path not expanded. Use $HOME instead ~/.bashrc # In strings, use "$HOME/.bashrc" # SC2181: Check exit code directly with `if`, not indirectly in a list some_command if [ $? -eq 0 ]; then # Better: if some_command; then # SC2206: Quote to prevent word splitting or set IFS array=( $items ) # Should use: array=( $items )

SC3000-3999: POSIX Compliance Issues

▼
bash
复制代码
# SC3010: In POSIX sh, use 'case' instead of 'cond && foo' [[ $var == "value" ]] && do_something # Not POSIX # SC3043: In POSIX sh, use 'local' is undefined function my_func() { local var=value # Not POSIX in some shells }

Practical Configuration Examples

Minimal Configuration (Strict POSIX)

▼
bash
复制代码
#!/bin/bash # Configure for maximum portability shellcheck \ --shell=sh \ --external-sources \ --check-sourced \ script.sh

Development Configuration (Bash with Relaxed Rules)

▼
bash
复制代码
#!/bin/bash # Configure for Bash development shellcheck \ --shell=bash \ --exclude=SC1091,SC2119 \ --enable=all \ script.sh

CI/CD Integration Configuration

▼
bash
复制代码
#!/bin/bash set -Eeuo pipefail # Analyze all shell scripts and fail on issues find . -type f -name "*.sh" | while read -r script; do echo "Checking: $script" shellcheck \ --shell=bash \ --format=gcc \ --exclude=SC1091 \ "$script" || exit 1 done

.shellcheckrc for Project

▼
text
复制代码
# Shell dialect to analyze against shell=bash # Enable optional checks enable=avoid-nullary-conditions,require-variable-braces,check-unassigned-uppercase # Disable specific warnings # SC1091: Not following sourced files (many false positives) disable=SC1091 # SC2119: Use function_name instead of function_name -- (arguments) disable=SC2119 # External files to source for context external-sources=true

Integration Patterns

Pre-commit Hook Configuration

▼
bash
复制代码
#!/bin/bash # .git/hooks/pre-commit #!/bin/bash set -e # Find all shell scripts changed in this commit git diff --cached --name-only | grep '\.sh$' | while read -r script; do echo "Linting: $script" if ! shellcheck "$script"; then echo "ShellCheck failed on $script" exit 1 fi done

GitHub Actions Workflow

▼
yaml
复制代码
name: ShellCheck on: [push, pull_request] jobs: shellcheck: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Run ShellCheck run: | sudo apt-get install shellcheck find . -type f -name "*.sh" -exec shellcheck {} \;

GitLab CI Pipeline

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

Handling ShellCheck Violations

Suppressing Specific Warnings

▼
bash
复制代码
#!/bin/bash # Disable warning for entire line # shellcheck disable=SC2086 for file in $(ls -la); do echo "$file" done # Disable for entire script # shellcheck disable=SC1091,SC2119 # Disable multiple warnings (format varies) command_that_fails() { # shellcheck disable=SC2015 [ -f "$1" ] && echo "found" || echo "not found" } # Disable specific check for source directive # shellcheck source=./helper.sh source helper.sh

Common Violations and Fixes

SC2086: Double quote to prevent word splitting

▼
bash
复制代码
# Problem for i in $list; do done # Solution for i in $list; do done # If $list is already quoted, or for i in "${list[@]}"; do done # If list is an array

SC2181: Check exit code directly

▼
bash
复制代码
# Problem some_command if [ $? -eq 0 ]; then echo "success" fi # Solution if some_command; then echo "success" fi

SC2015: Use if-then instead of && ||

▼
bash
复制代码
# Problem [ -f "$file" ] && echo "exists" || echo "not found" # Solution - clearer intent if [ -f "$file" ]; then echo "exists" else echo "not found" fi

SC2016: Expressions don't expand in single quotes

▼
bash
复制代码
# Problem echo 'Variable value: $VAR' # Solution echo "Variable value: $VAR"

SC2009: Use pgrep instead of grep

▼
bash
复制代码
# Problem ps aux | grep -v grep | grep myprocess # Solution pgrep -f myprocess

Performance Optimization

Checking Multiple Files

▼
bash
复制代码
#!/bin/bash # Sequential checking for script in *.sh; do shellcheck "$script" done # Parallel checking (faster) find . -name "*.sh" -print0 | \ xargs -0 -P 4 -n 1 shellcheck

Caching Results

▼
bash
复制代码
#!/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

Output Formats

Default Format

▼
bash
复制代码
shellcheck script.sh # Output: # script.sh:1:3: warning: foo is referenced but not assigned. [SC2154]

GCC Format (for CI/CD)

▼
bash
复制代码
shellcheck --format=gcc script.sh # Output: # script.sh:1:3: warning: foo is referenced but not assigned.

JSON Format (for parsing)

▼
bash
复制代码
shellcheck --format=json script.sh # Output: # [{"file": "script.sh", "line": 1, "column": 3, "level": "warning", "code": 2154, "message": "..."}]

Quiet Format

▼
bash
复制代码
shellcheck --format=quiet script.sh # Returns non-zero if issues found, no output otherwise

Best Practices

  1. Run ShellCheck in CI/CD - Catch issues before merging
  2. Configure for your target shell - Don't analyze bash as sh
  3. Document exclusions - Explain why violations are suppressed
  4. Address violations - Don't just disable warnings
  5. Enable strict mode - Use --enable=all with careful exclusions
  6. Update regularly - Keep ShellCheck current for new checks
  7. Use pre-commit hooks - Catch issues locally before pushing
  8. Integrate with editors - Get real-time feedback during development

Resources

  • ShellCheck GitHub: https://github.com/koalaman/shellcheck
  • ShellCheck Wiki: https://www.shellcheck.net/wiki/
  • Error Code Reference: https://www.shellcheck.net/
测试与安全
效率工具

快捷安装

复制到终端去安装 Skill

npxskillsaddwshobson/agents--skill"shellcheck-configuration"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。
cloud-scheduler-job-creator
自动处理 Google Cloud Platform 中的云调度任务创建,提供符合最佳实践的配置方案与生产级代码生成,支持计算、存储、大数据及机器学习服务的集成部署。