shellcheck插件不生效的主因是文件语法高亮类型不匹配（需为bash或shell-unix-generic）或sublime未加载shellcheck路径；须确认右下角显示正确语法、shellcheck命令可用、插件配置启用且sublime已重启。
ShellCheck插件安装后不生效，Ctrl+Shift+P 找不到命令
常见原因是插件未正确关联到 Bash/Shell 文件类型，或 Sublime Text 没有识别脚本的 shebang。ShellCheck 插件（如 SublimeLinter-shellcheck）依赖文件语法高亮类型触发检查。
- 确认当前文件右下角显示的是
Bash或Shell-Unix-Generic，不是Plain Text；点击右下角文字手动切换，或保存为.sh后缀再打开 - 确保已安装
shellcheckCLI 工具本身：shellcheck --version能正常输出；若用 Homebrew 安装过但路径不在$PATH中，需在 Sublime 的SublimeLinter.sublime-settings里显式指定"executable": "/usr/local/bin/shellcheck" - 插件安装后需重启 Sublime Text —— 仅重载插件包不够，部分 linting 功能在启动时初始化
企业脚本中大量使用 source 或 . 引入外部变量，ShellCheck 报 SC1091 却无法跳过
SC1091 是 ShellCheck 对“找不到被 source 文件”的警告，企业脚本常依赖统一的配置库路径（如 /opt/scripts/lib/common.sh），但 ShellCheck 默认只查当前目录和子目录。
- 用
# shellcheck source=/opt/scripts/lib/common.sh在source行上方添加注释，强制告知路径；注意路径必须是绝对路径或相对于项目根目录的相对路径 - 若多个脚本共用同一套 lib，可在项目根目录建
.shellcheckrc，写入source_path="/opt/scripts/lib"，并确保 SublimeLinter 配置中启用了该文件读取（"config_file": true） - 避免全局禁用
SC1091：加# shellcheck disable=SC1091会掩盖真实路径错误，上线后可能因环境差异导致 sourced 文件缺失
CI 流水线要求与本地 Sublime 检查结果一致，但 shellcheck -f gcc 输出格式和 Sublime 不匹配
SublimeLinter-shellcheck 默认使用 -f json 格式解析结果，而 CI 常用 -f gcc 便于集成到 Jenkins/GitLab CI 的静态分析报告中。二者规则相同，但字段结构不同，直接复用配置会漏报。
- 不要在 CI 中改用
-f json—— 多数 CI 插件（如 GitLab 的shellcheckanalyzer）硬编码支持gcc格式，强行换格式会导致解析失败 - Sublime 侧保持默认
-f json，CI 侧用原生shellcheck -f gcc *.sh；关键是要统一 ShellCheck 版本：运行shellcheck --version，确保本地和 CI 容器中版本号完全一致（如0.9.0），不同版本对同一条语句的检测粒度可能不同 - 企业级脚本常含 Bash 4+ 特性（如
[[正则匹配、declare -A），需在 CI 和本地都启用-s bash参数，否则 ShellCheck 默认按 POSIX sh 解析，误报大量SC2034、SC2154
大体积运维脚本（>2000 行）开启实时 lint 导致 Sublime 卡顿
ShellCheck 本身是单线程执行，对长脚本分析耗时明显，SublimeLinter 默认在保存或修改后自动触发，频繁扫描会阻塞 UI。
- 关闭实时 lint，改为仅保存时检查：在
SublimeLinter.sublime-settings中设"lint_mode": "save"，避免编辑过程中反复调用 - 排除非核心逻辑段落：用
# shellcheck disable=SC2001,SC2086注释临时禁用特定规则（仅限已知安全的场景，如动态构建命令字符串），但禁止整块禁用disable=all - 真正影响性能的是
shellcheck进程启动开销，而非脚本长度 —— 确保shellcheck是编译版（非 shell 脚本包装版），macOS 上 Homebrew 安装的默认就是二进制版；Linux 若从源码编译，务必用cabal build --ghc-options="-O2"
企业脚本审核真正的难点不在工具链打通，而在规则共识：哪些 SC 编号必须修复，哪些可豁免，得和运维团队、SRE 共同维护一份 shellcheck-whitelist.md，而不是靠个人经验判断。
