未安装 shellcheck 时需按系统选择对应命令安装：Ubuntu/Debian 用 apt，CentOS/RHEL 8+ 用 dnf，RHEL 7 需先启用 EPEL，macOS 用 brew；禁用 pip 安装。
shellcheck 命令没找到怎么办
直接运行 shellcheck 报错 “command not found”，说明它根本没装。Ubuntu/Debian 系统用 sudo apt install shellcheck；CentOS/RHEL 8+ 用 sudo dnf install ShellCheck（注意大小写）；RHEL 7 或旧版需先启用 EPEL 源再安装。macOS 用户用 Homebrew：brew install shellcheck。别试图用 pip 装，官方不支持，装了也跑不起来。
检查脚本时为什么总报 SC2086（未加引号展开）
这是 shellcheck 最常报的警告之一，典型场景是 echo $VAR 或 cp $SRC $DST。当 $VAR 含空格或通配符时，shell 会做单词拆分和 glob 展开，导致行为意外。修复方式就是加双引号：echo "$VAR"、cp "$SRC" "$DST"。但注意：如果真需要拆分（比如遍历数组），得用 "${arr[@]}" 而不是 $arr —— 后者只取首元素，且不加引号还会二次拆分。
如何跳过某一行的特定警告
不是所有提示都要改，比如你明确要用 eval，shellcheck 会报 SC2094，这时可在该行末尾加注释屏蔽：eval "$cmd" # shellcheck disable=SC2094。多个警告用逗号分隔：# shellcheck disable=SC2086,SC2034。注意：不能写成 disable: SC2086，冒号和空格都会让注释失效；也不能放在上一行，必须紧贴被检查的代码行末。
CI 中集成 shellcheck 但总因警告失败
默认 shellcheck 遇到 warning 就返回非零退出码，CI 流程直接中断。想只报错不停止，加 -e 参数过滤掉 warning 级别：shellcheck -e SC2086,SC2154 script.sh。更稳妥的做法是先用 shellcheck -f json script.sh 输出结构化结果，再由脚本判断是否含 "level": "error" 字段——毕竟真正该阻断的是 error，不是 warning。
真正容易被忽略的是 shebang 行的影响：如果脚本开头是 #!/bin/sh，shellcheck 默认按 POSIX sh 解析，此时 [[ 或 $(( )) 就会报错；若实际运行在 bash 下，得显式指定 #!/usr/bin/env bash 并加 # shellcheck shell=bash 注释，否则检查结果和运行时行为对不上。
