ShellCheck 在 VSCode 中需同时满足插件启用、CLI 可执行、文件识别为 shellscript、配置项 shellcheck.enable 为 true 四个条件才能正常工作。
ShellCheck 是目前 VSCode 里唯一能稳定提供实时、语义级 Shell 脚本检查的方案，但装了插件 ≠ 能用——它必须同时满足四个硬性条件：插件启用、CLI 可执行、文件被识别为 shellscript、配置项 shellcheck.enable 为 true。
为什么 ShellCheck 插件点了安装却没任何提示？
VSCode 不会自动激活 ShellCheck，右下角不显示 “ShellCheck” 字样，基本等于没跑起来。
- 打开一个
.sh文件，点击右下角语言标识（常是Plain Text），手动选Shell Script；否则它连语法解析器都不加载 - 按
Ctrl+Shift+P输入ShellCheck: Run ShellCheck，如果报错command 'shellcheck.run' not found，说明插件根本没启动——重启 VSCode 是最快验证方式 - 确认插件已启用：在扩展面板搜
timonwong.shellcheck，状态必须是 “已启用”，不是“已安装”
明明终端能跑 shellcheck --version，VSCode 却提示 “not found”？
VSCode 的 PATH 和你终端的 PATH 常不一致，尤其用了 nvm、asdf、conda 或 WSL 的用户。
- 终端运行
which shellcheck（macOS/Linux）或where shellcheck（Windows CMD），拿到完整路径，比如/opt/homebrew/bin/shellcheck - 在 VSCode 设置中搜索
shellcheck.executablePath，填入这个完整路径——不能只写shellcheck - Windows 用户若用 WSL 编辑文件，别在 Windows 版 VSCode 里硬配路径，直接装
Remote - WSL扩展更可靠
为什么 local var=1 或 [[ 也被标红？
ShellCheck 默认按 POSIX sh 检查，而你的脚本实际运行在 Bash 下，类型错位导致大量“合法语法误报”。
- 脚本第一行必须有明确 shebang：
#!/usr/bin/env bash（比#!/bin/bash更兼容） - 在
settings.json中加"shellcheck.shell": "bash"，强制插件按 Bash 解析 - 别用
-e SC2086屏蔽未引号变量警告——那是真 bug 高发区，echo $var在含空格时必崩
保存后没反应？检查这两个开关是否真开着
VSCode 默认不自动检查，也不靠后缀判断语言，全靠显式配置驱动。
- 确保
shellcheck.enable是true（不是"true"字符串） - 确保
shellcheck.runOnSave是true；设成onType容易卡顿，不推荐 - 在
settings.json加上"files.associations": {"*.sh": "shellscript"}，否则新建文件永远是Plain Text
最容易被忽略的是：shebang 必须存在且保存后才生效，修改完 settings.json 后记得重开文件或重启窗口。ShellCheck 不是“装了就灵”的工具，它是四个齿轮咬合才能转起来的静态检查链——少一个，整个链就断在那儿。
