lang: zh slug: shellcheck title: ‘ShellCheck：39,456 个 GitHub 星星’ description: ‘ShellCheck（SC）是bash/sh shell脚本的静态分析工具。 与 Docker、GitHub Actions、VS Code 和 CI/CD 管道集成。 涵盖安装、配置、CI 集成和生产强化。’ tags: [“automation”, “ci-cd”, “github”, “guide”, “open-source”, “reference”, “tutorial”] date: 2026-05-19 00:00:00+08:00 lastmod: 2026-05-19 00:00:00+08:00 tech_stack: [] application_domain: Dev Utils source_version: ’' licensing_model: Open Source license_type: GPL-3.0 file_size: ’' file_md5: ’' download_url: ’' backup_url: ’' github_repo: ‘https://github.com/koalaman/shellcheck' last_maintained: ‘2026-05-19’ draft: false categories: [‘dev-utils’] aliases:- /帖子/shellcheck/ 常见问题解答：
- q: ‘ShellCheck 支持哪些 shell？’ a: ‘ShellCheck 支持 bash、dash、sh、ksh 和 busybox sh。 它不支持PowerShell或fish，并且zsh支持只是部分的。 您可以使用 –shell 标志（bash、sh、dash 或 ksh）或通过脚本的 shebang 行指定目标 shell。
- q: ‘如何在不本地安装的情况下运行 ShellCheck？’ a: ‘使用官方 Docker 镜像：docker run –rm -v “$PWD:/mnt” koalaman/shellcheck:stable /mnt/script.sh。 该镜像基于Alpine Linux，大小约为15 MB。 固定到特定标签，例如 v0.11.0，以实现可重复的 CI 构建。
- q: ‘如何抑制特定的 ShellCheck 警告？’
a: ‘在警告之前的行添加内联指令，例如 # shellcheck disable=SC2086。 对于项目范围的抑制，请将disable=SC2086 添加到位于存储库根目录或$HOME 中的.shellcheckrc 文件中。 每项检查都记录在 shellcheck.net/wiki/
中。 - q: ‘ShellCheck 可以自动修复 shell 脚本吗？’ a: ‘shellcheck.net 的 Web 界面为许多常见问题提供自动修复建议，CLI 在其输出中显示建议的修复，但 CLI 不会就地修改文件。 一些第三方工具包装 ShellCheck 以自动应用修复。
- q: ‘ShellCheck 无法捕获哪些类型的错误？’
a: ‘ShellCheck 执行静态分析而不执行脚本，因此它无法检测运行时逻辑错误、业务逻辑错误或具有有效语法的无限循环等性能问题。 eval“$DYNAMIC_CMD”等动态行为本质上是不可分析的，并且不支持 PowerShell 和 CMD 等 Windows 原生脚本。
特征图片：/images/articles/shellcheck-39-456-github-stars-complete-setup-guide.png——{{< 资源信息 >}}ShellCheck 是在 shell 脚本投入生产之前捕获它们的事实上的标准。 它拥有 39,456+ GitHub star 和维护的开源社区，是 bash、sh、dash 和 ksh 脚本采用最广泛的静态分析工具。 本指南逐步介绍了 ShellCheck 的安装、将其与编辑器和 CI/CD 管道集成以及对其进行强化以供生产使用。
- 语义分析：检测未加引号的变量、无法访问的代码和屏蔽的退出代码
- 可移植性检查：标记
/bin/sh脚本中的bashisms，旨在实现 POSIX 合规性 - 安全审核：识别命令注入向量和不安全的评估模式
- 风格强制：建议使用现代结构替代已弃用的语法## ShellCheck 的工作原理ShellCheck 作为多阶段分析管道运行。 了解此架构有助于调整性能或解释结果。### 架构概述```` 源脚本 → 词法分析器 → 解析器 (AST) → 分析器 → 报告器 ↓ ↓ ↓ 令牌语法树 SC-警告
2. **解析器**：从令牌流构建 AST，处理特定于 shell 的语法怪癖
3. **分析器**：遍历 AST 并应用约 280 多个规则，每个规则映射到一个 SC 错误代码
4. **Reporter**：将结果格式化为终端输出、JSON、CheckStyle XML、GCC 兼容警告或 SARIF### 严重级别每个 ShellCheck 发现结果都带有四个严重级别之一：| Level | Exit Code Impact | Example |
|-------|-----------------|---------|
| Error | Non-zero exit | Syntax error, undefined variable |
| Warning | Non-zero exit | Unquoted variable (SC2086) |
| Info | Zero exit | Style suggestion |
| Style | Zero exit | Formatting preference |### 核心检查类别- **SC1xxx**：语法和解析问题（例如，SC1007 — `=` 后的空格）
- **SC2xxx**：语义和可移植性警告（例如，SC2086 - 不带引号的变量）
- **SC3xxx**：Bash/dash/ksh 特定的兼容性说明
- **SC4xxx**：可选检查和实验规则## 安装和设置ShellCheck 可在每个主要平台上使用。 安装时间不到两分钟。### Linux（APT / Debian / Ubuntu）````
bas
h
# 更新包索引
须藤apt更新# 安装 ShellCheck
sudo apt install -y shellcheck# 验证版本
shellcheck --版本
# ShellCheck - shell s```
bas
h
# 更新包索引
须藤apt更新
# 安装 ShellCheck
sudo apt install -y shellcheck
# 验证版本
shellcheck --版本
# ShellCheck - shell脚本分析工具
# 版本：0.11.0
# 许可证：GNU 通用公共许可证，版本 3
# 网站：https://www.shellcheck.net
```通过
Homebrew 安装
酿造安装shellcheck# 验证
shellcheck --版本
````### Windows（通过 Chocolatey）````
powershel
l
# 通过 Chocolatey 安装（管理员提示符）
choco 安装 shellcheck# 验证
shellcheck --版本
````### Docker（平台无关）````
bas
h
# 通过 Docker 运行 ShellCheck，无需本地``bash
# 通过DNF安装
须藤 dnf install -y shellcheck
# 验证
shellcheck --版本
docker run –rm -v “$PWD:/mnt” koalaman/shellcheck:stable \
bas
h
# 通过自制程序安装
酿造安装shellcheck
# 验证
shellcheck --版本
```
D
:/mnt" koalaman/shellcheck:v0.11.0 \
/mnt/deploy.sh
````### 从源代码构建（Haskell Stack）````
bas
h
# Cl```
powershel
l
# 通过 Chocolatey 安装（管理员提示符）
choco 安装 shellcheck
# 验证
shellcheck --版本
``# 或使用 Cabal 构建
阴谋集团更新
阴谋集团安装
````### 预提交挂钩````
bas
h
# 添加到您的 .pre-commit-config.yaml
回购协议：
- 仓库：https://githu```
bas
h
# 通过 Docker 运行 ShellCheck，无需本地安装
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
/mnt/deploy.sh
# 查看当前目录下所有脚本
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
/mnt/*.sh
# 固定到特定版本以进行可重复的 CI 构建
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:v0.11.0 \
/mnt/deploy.sh
````{
"shellcheck.executablePath": "shellcheck",
"shellcheck.exclude": ["SC1090", "SC1091"],
"shellcheck.severity": "警告",
“shellcheck.run”：“onType”
}
````### Vim / Neovim使用 ALE（异步 Lint 引擎）：```
vi
m
" .vimrc 或 init.vim
让 g:ale_linters = {
\ 'sh': ['shellcheck'],
\}" 保存并输入时运行
让 g:ale_lint_on_save = 1
让 g:ale_lint_on_text_changed = '始终'
````在
Neovi```
bas
h
中使用原生 LSP
# 克隆存储库
git 克隆 https://github.com/koalaman/shellcheck.git
cd shell检查
# 使用堆栈构建
堆栈安装
# 或者使用 Cabal 构建
阴谋集团更新
阴谋集团安装
Emacs``埃利普 #
;; init.el 与 Flycheck (add-hook ‘sh-mode-hook #‘flycheck-mode) （setq Flycheck-shellcheck-严重性“警告”） ````### 崇高文本通过包控制安装：**SublimeLinter-``` bas h
添加到您的 .pre-commit-config.yaml #
回购协议：
- 仓库：https://github.com/koalaman/shellcheck-precommit 修订版：v0.11.0 挂钩：
- id：shell检查 参数：[“–严重性=警告”]
在 CI 中运行 ShellCheck 可防止合并有错误的脚本。 以下是 GitHub Actions、GitLab CI 和 Jenkins 的即用型配置。### GitHub 操作````
yam
l
# .github/workflows/shellcheck.yml
名称： ShellCheck上：[推，拉请求]职位：
外壳检查：
运行：ubuntu-latest
步骤：
- 名称：签出存储库
使用：actions/checkout@v4- 名称：运行 ShellCheck
使用：ludeeus/action-s```
jso
n
// 设置.json
{
"shellcheck.executablePath": "shellcheck",
"shellcheck.exclude": ["SC1090", "SC1091"],
"shellcheck.severity": "警告",
“shellcheck.run”：“onType”
}
````版本：````
yam
l
# .github/workflows/shellcheck-manual.yml
名称：ShellCheck手册上：[推，拉请求]职位：
外壳检查：
运行：ubuntu-latest
步骤：
- 使用：actions/checkout@v4- 名称：安装 ShellCheck
```
vi
m
" .vimrc 或 init.vim
让 g:ale_linters = {
\ 'sh': ['shellcheck'],
\}
" 保存并输入时运行
让 g:ale_lint_on_save = 1
让 g:ale_lint_on_text_changed = '始终'
```0.11.0/shellcheck" /usr/local/bin/- 名称：检查所有 shell 脚本
运行： |
寻找 。 -名称“*.sh”-type f -print0 | \
xargs -0 shellcheck --severity=警告 --format=tty
````### GitLab CI````
yam
l
# .```
lu
a
-- init.lua (nvim-lspconfig)
需要（'lspconfig'）.bashls.setup {
设置={
bashIde = {
shellcheckPath = “shell检查”
}
}
}
```
llchec
k
--severity=警告 {} +
规则：
- 如果：$CI_PIPELINE_SOURCE ==“merge_request_event”
- 如果：$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
````### Jenk```
elis
p
;; init.el 与 Flycheck
(add-hook 'sh-mode-hook #'flycheck-mode)
（setq Flycheck-shellcheck-严重性“警告”）
``嘘'''
#!/bin/bash
设置-euo管道故障如果 ！ 命令 -v shellcheck &> /dev/null; 然后
echo "正在安装```
jso
n
// SublimeLinter.sublime-settings
{
"linters": {
“外壳检查”：{
“可执行文件”：“shellcheck”，
“args”：[“--严重性=警告”]
}
}
}
````0
| \
xargs -0 shellcheck --severity=警告
'''
}
}
}发布{
失败{
echo "ShellCheck 发现问题。查看构建日志。"
}
}
}
````### CircleCI````
yam
l
# .circleci/config.yml
版本：2.1
球体：
shellcheck：circleci/shellcheck@3.2.0工作```
yam
l
# .github/workflows/shellcheck.yml
名称： ShellCheck
上：[推，拉请求]
职位：
外壳检查：
运行：ubuntu-latest
步骤：
- 名称：签出存储库
使用：actions/checkout@v4
- 名称：运行 ShellCheck
使用：ludeeus/action-shellcheck@master
环境：
严重性：警告
与：
忽略路径：>-
./供应商
./第三方
```他已被分配但未使用"# 阻塞后重新启用
# shellcheck 启用=SC2086
回显“$PROPERLY_QUOTED”
````### 配置文件（.shellcheckrc）````
bas
h
# .shellcheckrc — 项目级配置
# 放置在 repo 根目录或 $HOME/.shellcheckrc 中# 为不带 shebang 的脚本设置 shell 方言
外壳=bash# 全局排除特定检查
禁用=SC1090、SC1091、SC2155# 设置最低严重性（错误、警告、信息、样式）
严重性=警告# 启用选项```
yam
l
# .github/workflows/shellcheck-manual.yml
名称：ShellCheck手册
上：[推，拉请求]
职位：
外壳检查：
运行：ubuntu-latest
步骤：
- 使用：actions/checkout@v4
- 名称：安装 ShellCheck
运行： |
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz" | 焦油-xJf-
sudo cp“shellcheck-v0.11.0/shellcheck”/usr/local/bin/
- 名称：检查所有 shell 脚本
运行： |
寻找 。 -名称“*.sh”-type f -print0 | \
xargs -0 shellcheck --severity=警告 --format=tty
```
pt
.sh > shellcheck.xml# GCC 兼容警告（用于通用编辑器集成）
shellcheck --format=gcc script.sh# GitHub 安全选项卡集成的 SARIF 输出
shellcheck --format=sarif script.sh > shellcheck.sarif
````## 基准和实际用例ShellCheck 的采用范围涵盖个人开发人员到企业 CI/CD 管道。 以下是基准和使用指标。### 性能基准在 2024 标准 CI 运行器（Ubuntu 24.04、2 vCPU、4 GB RAM）上测试：| Script Size | Lines | Analysis Time | Memory Used |
|-------------|-------|---------------|-------------|
| Small | 50 | 0.05s | 12 MB |```
yam
l
# .gitlab-ci.yml
stages:
- lint
shellcheck:
stage: lint
image: koalaman/shellcheck-alpine:stable
script:
- find . -name "*.sh" -type f -exec shellcheck --severity=warning {} +
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```e
Guide**: Recommends ShellCheck for all shell scripts
- **NixOS**: Uses ShellCheck in the official package build pipeline
- **Debian / Ubuntu**: Packaged and maintained in the official repositories### 检测到的错误类别（1,000 个开源脚本的示例分析）| 检查代码 | 描述 | 检测率|```
groov
y
// 詹金斯文件
管道{
代理任何
阶段{
阶段（'ShellCheck'）{
步骤{
嘘'''
#!/bin/bash
设置-euo管道故障
如果！ 命令 -v shellcheck &> /dev/null; 然后
echo "正在安装 ShellCheck..."
apt-get update && apt-get install -y shellcheck
菲
找到。 -名称“*.sh”-type f -print0 | \
xargs -0 shellcheck --severity=警告
'''
}
}
}
发布{
失败{
echo "ShellCheck 发现问题。查看构建日志。"
}
}
}
```}" -name "*.sh" -type f -print0 | \
xargs -0 shellcheck --severity="$SEVERITY" "${EXCLUDES[@]}"echo "所有脚本都通过了 ShellCheck，严重程度为：$SEVERITY"
````### SARIF 上传 GitHub 安全仪表板````
yam
l
# .github/workflows/security-scan.yml
名称： 安全扫描
上：[推，拉请求]职位：
扫描：
运行：ubuntu-latest
权限：
安全事件：写
内容： 阅读
步骤：
- 使用：actions/checkout@v4- 名称：运行 ShellCheck SARIF
运行： |
寻找 。 -名称“*.sh”-type f -print0 | \
xargs -0 shellcheck --format=sarif > shellcheck.sarif || 真的- 名称：上传到 GitHub 安全
使用：github/codeql-action/upload-sarif@v```
yam
l
# .circleci/config.yml
版本：2.1
球体：
shellcheck：circleci/shellcheck@3.2.0
工作流程：
棉绒：
职位：
- shell检查/检查：
严重程度：“警告”
排除：“SC1090、SC1091”
``` -name "*.sh" -exec shellcheck --severity=警告 {} +FROM alpine:3.20 AS 运行时
复制 --from=lint /scripts/deploy.sh /usr/local/bin/
入口点 [“/usr/local/bin/deploy.sh”]
````### Monitoring ShellCheck in CI将 ShellCheck 失败作为团队指标进行跟踪：````
bas
h
#!/bin/bash
# ci-metrics.sh — 随着时间的推移跟踪 shellcheck 警告计数警告=$(查找 .-name "*.sh" ```
bas
h
#!/bin/bash
# shellcheck 禁用=SC2086
echo $UNQUOTED_VAR # 此行禁用 SC2086
# shellcheck 禁用=SC2034
UNUSED_VAR="已分配但未使用"
# 阻塞后重新启用
# shellcheck 启用=SC2086
回显“$PROPERLY_QUOTED”
```-----|---------|--------|---------------|
| 静态分析深度| 语义（基于 AST）| 仅语法 | 解析器/格式化器 | 模式匹配 |
| 错误计数 | 约 280 多项检查 | 约 20 个错误 | 0（格式化程序）| 约 40 种模式 |
| Bash/sh/dash/ksh 支持 | 所有方言 | 仅限 Bash | POSIX + ```
bas
h
# .shellcheckrc — 项目级配置
# 放置在 repo 根目录或 $HOME/.shellcheckrc 中
# 为不带 shebang 的脚本设置 shell 方言
外壳=bash
# 全局排除特定检查
禁用=SC1090、SC1091、SC2155
# 设置最低严重性（错误、警告、信息、样式）
严重性=警告
# 启用可选检查
启用=需要变量大括号，检查集e-抑制
# 指定外部源（对于源文件）
外部来源=true
```-3-子句 | GPL-2.0+ |### 何时选择每种工具- **ShellCheck**：通用 shell 脚本质量和安全审核。 默认选择。
- **`bash -n`**：在没有其他可用的情况下对 bash 脚本进行快速语法验证。
- **shfmt**：代码格式化和样式规范化。 补充 ShellCheck（而非替代品）。
- **checkbashisms**：特定于 Debian 的可移植性检查。 为 Debian/Ubuntu 打包时使用。## 限制和诚实的屁股```
bas
h
# 仅报告错误和警告（无信息/样式）
shellcheck --severity=警告 script.sh
# 只报告错误
shellcheck --severity=error script.sh
```**：它无法确定您的“curl”命令是否针对正确的端点
- **业务逻辑错误**：它验证语法，而不是验证您的备份脚本是否备份正确的 d```
bas
h
# 人类可读的终端输出（默认）
shellcheck --format=tty script.sh
# 用于编程处理的 JSON 输出
shellcheck --format=json script.sh > shellcheck-report.json
# CheckStyle XML（Jenkins、GitLab 兼容）
shellcheck --format=checkstyle script.sh > shellcheck.xml
# GCC 兼容警告（用于通用编辑器集成）
shellcheck --format=gcc script.sh
# GitHub 安全选项卡集成的 SARIF 输出
shellcheck --format=sarif script.sh > shellcheck.sarif
不支持 ```
s
-native 脚本（PowerShell、CMD）### 构建和依赖关系注意事项- 从源代码构建时，Haskell 运行时会向 Docker 镜像添加约 30 MB
- 预构建的二进制文件（推荐的方法）没有运行时依赖性
- CI 管道应固定到特定版本，以避免版本中的新检查导致构建中断## 常见问题### ShellCheck 支持哪些 shell？ShellCheck 支持 bash、dash、sh、ksh 和 busybox sh。 它不支持 PowerShell、zsh（部分）或 Fish。 使用“--shell bash|sh|dash|ksh”或通过脚本中的 shebang 行指定目标 shell。### 如何抑制特定的 ShellCheck 警告？在警告之前的行上使用内联指令：“# shellcheck disable=SC2086”。 对于项目范围的抑制，请将“disable=SC2086”添加到“.shellcheckrc”文件中。 每项检查都有一个 wiki 页面，网址为“https://www.shellcheck.net/wiki/SC2086”，解释其基本原理。### ShellCheck 可以自动修复我的脚本吗？[shellcheck.net](https://www.shellcheck.net) 的 Web 界面为许多常见问题提供自动修复建议。 CLI 工具在其输出中显示建议的修复，但不会就地修改文件。 一些第三方工具包装 ShellCheck 以自动应用修复。### 如何将 ShellCheck 与预提交挂钩集成？将“https://github.com/koalaman/shellcheck-precommit”中的官方预提交挂钩添加到“.pre-commit-config.yaml”中。 设置 `args: ["--severity=warning"]` 以阻止带有警告的提交，或设置 `args: ["--severity=error"]` 以仅阻止错误。### ShellCheck适合安全审计吗？ShellCheck 可识别常见的安全模式，例如命令注入 (SC2096)、不安全的 eval 使用以及可能恶意扩展的未加引号的变量。 但是，它并不能替代专用安全扫描仪。 将其与 Semgrep 或 GitHub CodeQL 等工具结合使用，可实现全面的安全覆盖。### 为什么 ShellCheck 会标记有效的代码```
bas
h
#!/bin/bash
设置-euo管道故障
严重性=“警告”
SCRIPT_DIRS=(“脚本/”“bin/”“部署/”)
排除=()
# 构建排除列表
对于 SC1090 SC1091 SC2155 中的代码； 做
排除+=("-e" "$code")
完成
# 查找并检查所有 shell 脚本
查找“${SCRIPT_DIRS[@]}”-name“*.sh”-type f-print0| \
xargs -0 shellcheck --severity="$SEVERITY" "${EXCLUDES[@]}"
echo "所有脚本都通过了 ShellCheck，严重程度为：$SEVERITY"
```用于可重现
CI 构建的其他特定版本。 该镜像基于 Alpine Linux，大小约为 15 MB。＃＃ 结论ShellCheck是最成熟、最广泛采用的shell脚本静态分析工具。 拥有超过 39,456 个 GitHub star、全面的 CI/CD 集成以及对每个主要编辑器的支持，它属于每个开发人员工具链。 从 Docker 一行开始以获得即时反馈，为团队 con``yaml 添加 `.shellcheckrc` 项目配置
# .github/workflows/security-scan.yml
名称： 安全扫描
上：[推，拉请求]
职位：
扫描：
运行：ubuntu-latest
权限：
安全事件：写
内容： 阅读
步骤：
- 使用：actions/checkout@v4
- 名称：运行 ShellCheck SARIF
运行： |
寻找 。 -名称“*.sh”-type f -print0 | \
xargs -0 shellcheck --format=sarif > shellcheck.sarif || 真实
- 名称：上传到 GitHub 安全
使用：github/codeql-action/upload-sarif@v3
如果：总是（）
与：
sarif_file: shellcheck.sarif
``将上述任何工具部署到生产中，您将需要坚实的基础设施。 dibi8实际使用和推荐的两个选项：- **{< aff "digitalocean" "footer-cta-legacy" "DigitalOcean" >}}** — 200 美元免费赠金，为期 60 天，覆盖全球 14 个以上区域。 运行开源人工智能工具的独立开发者的默认选项。
- **{< aff "htstack" "footer-cta-legacy" "HTStack" >}}** — 从中国大陆低延迟访问的香港 VPS。 这与托管 dibi8.com 的 IDC 是同一个 IDC——在生产中经过了实际考验。*附属链接 - 它们不会花费您额外的费用，并且有助于保持 dibi8.com 的运行。*## 来源和 F```
dockerfil
e
# Dockerfile
来自 koalaman/shellcheck:stable AS lint
工作目录/脚本
复制。 。
运行找到 . -name "*.sh" -exec shellcheck --severity=警告 {} +
FROM alpine:3.20 AS 运行时
复制 --from=lint /scripts/deploy.sh /usr/local/bin/
入口点 [“/usr/local/bin/deploy.sh”]
```
aman
/shellcheck/releases/tag/v0.11.0)
- [ShellCheck 预提交挂钩](https://github.com/koalaman/shellcheck-precommit)
- [ludeeus/action-shellcheck — GitHub Action](https://github.com/ludeeus/action-shellcheck)
- [Google Shell 风格指南](https://google.github.io/styleguide/shellguide.html)
- [shfmt — Shell 格式化程序](https://github.com/mvdan/sh)
- [c```
bas
h
#!/bin/bash
# ci-metrics.sh — 随着时间的推移跟踪 shellcheck 警告计数
警告=$(find . -name "*.sh" -exec shellcheck --severity=warning --format=json {} + | \
jq'. | 长度')
echo“shellcheck_warnings $WARNINGS”>>metrics.txt
```
ellCheck
](https://github.com/koalaman/shellcheck)
- [ShellCheck官方网站](https://www.shellcheck.net/)
- [ShellCheck 预提交挂钩](https://github.com/koalaman/shellcheck-precommit)
- [ludeeus/action-shellcheck](https://github.com/ludeeus/action-shellcheck)
- [shfmt](https://github.com/mvdan/sh)
- [Google Shell 风格指南](https://google.github.io/styleguide/shellguide.html)
featureImage: /images/articles/shellcheck39456-github.png
💬 留言讨论