根本原因是shellcheck二进制未被Sublime Text找到，需确认which shellcheck有输出、PATH在GUI中可见，并确保文件语法设为ShellScript、.sh后缀及SublimeLinter配置正确启用shellcheck。
SublimeLinter-shellcheck 安装失败或不触发检查？
根本原因通常是 shellcheck 二进制未被 Sublime Text 找到，而不是插件本身没装好。SublimeLinter 不自带 shellcheck，它只是调用系统已安装的命令行工具。
确认方式：终端运行 which shellcheck，如果返回空或报错，说明没装；如果返回路径（如 /usr/local/bin/shellcheck），但 Sublime 仍不工作，大概率是 PATH 环境变量在 GUI 应用中不可见。
- macOS 用户：若用 Homebrew 安装过
shellcheck，但 Sublime 启动自 Launchpad，需通过终端命令open -a "Sublime Text"启动，才能继承 shell 的 PATH - Linux 用户：确保
shellcheck在用户 PATH 中（比如放在~/bin/且该路径已写入~/.profile），并确认 Sublime 是从终端启动或已重载环境变量 - Windows 用户：需手动把
shellcheck.exe所在目录加进系统 PATH，推荐使用 官方 release 页面 下载 Windows 版本，解压后配置路径
Shell 脚本保存后没自动 lint？检查 SublimeLinter 配置项
默认情况下，SublimeLinter 只对语法正确的 Shell 文件启用检查。如果文件后缀不是 .sh，或 Sublime 当前识别的语法不是 ShellScript，SublimeLinter-shellcheck 就不会介入。
- 右下角查看当前语法：点击窗口右下角文字（如 “Plain Text”），选择
ShellScript→ 这会把文件关联到shellcheck - 确保文件有
.sh后缀；没有后缀或为.bash时，可能需要手动设置语法或修改 SublimeLinter 配置 - 检查用户配置：
Preferences → Package Settings → SublimeLinter → Settings，确认"linters": {"shellcheck": {"enabled": true}}，且"shellcheck"下的"executable"路径正确（例如 macOS 上设为"/usr/local/bin/shellcheck"）
shellcheck 报错太严格，想忽略某行或关闭特定警告？
shellcheck 支持行级禁用，但语法必须紧贴代码行，且只对当前行生效——放错位置（比如注释缩进不对、多写了空格）就无效。
- 忽略单行：在该行末尾加
# shellcheck disable=SC2086（SC2086 是参数未引号展开警告） - 忽略多行：在上一行写
# shellcheck disable=SC2086,SC2034，注意逗号后不能有空格 - 全局关闭某类警告不推荐：虽可在配置里加
"args": ["-e", "SC2086"]，但容易掩盖真实问题；优先用行级 disable + 注释说明原因 - 常见误用：
# shellcheck disable SC2086（缺等号）、# shellcheck disable= SC2086（等号后空格）、写在空行或注释块中间——这些都不会生效
为什么 .sh 文件里用了 #!/usr/bin/env bash 却还报 SC2148？
SC2148 是 “没有 shebang，脚本可能无法执行”，但它其实是个误导性提示：只要文件第一行是 #!/usr/bin/env bash 或类似 shebang，shellcheck 就不该报这个错。真正触发它的常见原因是：
- 文件开头有 BOM（Byte Order Mark）或不可见控制字符，导致
shellcheck没读到 shebang 行——用file script.sh和hexdump -C script.sh | head检查编码 - Sublime 默认保存为 UTF-8 with BOM（尤其 Windows 上），需手动改：菜单
File → Save with Encoding → UTF-8 - shebang 行前面有空行或空格——
shellcheck要求 shebang 必须是文件第一行（\n前不能有任何字符）
这个问题最常发生在跨平台编辑或从网页复制代码后——看似干净的文件，实际藏了不可见字符。
