shellcheck

ShellCheck - Shell 脚本静态分析

当用户提到 shellcheck、Shell lint、Bash 脚本分析或 SC 错误代码时，自动路由。

概述

ShellCheck 是一款基于 GPLv3 许可的静态分析工具，可识别 Bash/sh Shell 脚本中的错误。它可以检测：

• 语法错误和解析问题
• 导致意外行为的语义问题
• 引号问题和单词拆分错误
• POSIX 兼容性警告
• 风格和最佳实践违规

语音通知

执行工作流时，必须同时执行以下两项：

1. 发送语音通知：

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running the WORKFLOWNAME workflow from the ShellCheck skill"}' \
     > /dev/null 2>&1 &
   

2. 输出文本通知：

   Running the **WorkflowName** workflow from the **ShellCheck** skill...
   

工作流路由

工作流	触发条件	文件
分析	"shellcheck this", "lint script", "check shell"	Workflows/Analyze.md
修复	"fix shell errors", "apply shellcheck fixes"	Workflows/Fix.md
设置	"setup shellcheck", "configure shellcheck"	Workflows/Setup.md
解释	"explain SC2086", "what is SC code"	Workflows/Explain.md

快速参考

基本用法

# Check a script
shellcheck myscript.sh

# Specify shell dialect
shellcheck -s bash myscript.sh

# Exclude specific codes
shellcheck -e SC2086,SC2046 myscript.sh

# Output formats
shellcheck -f gcc myscript.sh      # Editor integration
shellcheck -f json myscript.sh     # Machine readable
shellcheck -f diff myscript.sh     # Auto-fix patches

常见 SC 代码

代码	问题	修复方法
SC2086	变量未加引号	"$var"
SC2046	命令替换未加引号	"$(cmd)"
SC2034	未使用的变量	删除或导出
SC2154	未赋值的变量	赋值或禁用
SC2155	声明和赋值应分开进行	拆分声明

行内指令

# Disable for next command
# shellcheck disable=SC2086
echo $var

# Disable for entire file (after shebang)
#!/bin/bash
# shellcheck disable=SC2086,SC2046

完整文档

• 错误代码：SkillSearch('shellcheck error codes') -> 加载 ErrorCodes.md
• 配置：SkillSearch('shellcheck config') -> 加载 Configuration.md
• CI/CD 集成：SkillSearch('shellcheck ci') -> 加载 Integration.md
• 最佳实践：SkillSearch('shellcheck practices') -> 加载 BestPractices.md

示例

示例 1：分析脚本

User: "shellcheck my deploy script"
-> Invokes Analyze workflow
-> Runs shellcheck with JSON output
-> Presents findings grouped by severity
-> Suggests fixes with wiki links

示例 2：修复常见问题

User: "fix the shellcheck errors in scripts/"
-> Invokes Fix workflow
-> Generates diff output
-> Applies fixes interactively
-> Re-runs validation

示例 3：为项目设置

User: "setup shellcheck for this repo"
-> Invokes Setup workflow
-> Creates .shellcheckrc
-> Adds pre-commit hook
-> Configures CI workflow

示例 4：解释错误代码

User: "what does SC2086 mean?"
-> Invokes Explain workflow
-> Fetches wiki documentation
-> Shows examples and fixes
-> Provides context-specific guidance

---

注意事项

• 在 [[ ]] 中，SC2086 不适用： Bash 的 [[ ]] 不会进行单词拆分，因此 [[ -n $var ]] 不加引号也是安全的。在 [[ ]] 代码块中禁用 SC2086，说明你把 lint 应用到了错误的语法结构，而不是规则本身有问题。
• SC2034 会对间接使用的变量发出警告： 通过 ${!prefix*} 间接引用、declare -p 内省或载入其他脚本的变量，都会触发“未使用”误报。使用 # shellcheck disable=SC2034 并添加注释说明间接引用的情况，不要全局屏蔽。
• Shebang 决定方言，而不是文件名： 使用 #!/bin/sh 的 script.sh 会按 POSIX sh 检查，并拒绝 [[ ]] 或数组等 Bash 专属语法。应设置正确的 shebang，或明确传入 -s bash；切勿依赖 .sh 扩展名。
• 在 .shellcheckrc 中使用 shellcheck -e SC2086,SC2046 会隐藏真实错误： 全项目禁用规则会叠加生效——一年后没人记得原因，未加引号的展开式却被发布到生产环境。优先使用带理由注释的行内禁用，而不是全局屏蔽。
• 跟踪 source 文件需要 -x 标志： 默认不会分析 source ./lib.sh。使用 shellcheck -x script.sh 进行完整检查，或添加 # shellcheck source=./lib.sh 指令。CI 配置经常漏掉这项，导致被 source 的文件未经过 lint 检查就被发布。
• -f diff 补丁要求脚本能够正常解析： 语法错误会导致完全不输出自动修复结果，且不会给出明确提示。如果 -f diff 没有输出，先不带 -f 运行并修复解析错误，然后再重新运行以生成补丁。