Shell脚本在VSCode中语法解析错误，大概率是插件冲突或语言模式未正确识别：需手动设为Shell Script模式、禁用sh/Bash Debug/Volar等干扰插件、配置绝对路径的shellcheck.executablePath并重启VSCode。
Shell脚本在 VSCode 中出现语法解析错误（比如高亮全灰、变量不识别、if 关键字没颜色、$VAR 不被当作变量），大概率不是脚本写错了，而是 Shell 相关插件之间抢了控制权——尤其是 ShellCheck、Volar、Bash Debug、sh（by foxundermoon）这几类插件常互相覆盖语言服务注册。
确认当前文件是否真被识别为 Shell Script
VSCode 不会自动把 .sh 文件当成 Shell 脚本处理，哪怕你装了 ShellCheck。右下角状态栏显示 “Plain Text”、“Bash” 或空着，就说明语言模式没对上，后续所有语法检查、补全、诊断都会失效。
- 打开任意
.sh文件，点击右下角语言标识，手动选 Shell Script（注意不是 Bash、Shell、POSIX Shell） - 若频繁回退，进
settings.json加配置："files.associations": {"*.sh": "shellscript"} - 改完必须重启 VSCode，否则关联不生效 —— 这步跳过，90% 的“插件不工作”问题都白查
排查 ShellCheck 与其它语言服务的接管冲突
ShellCheck 插件本身不提供语言服务，它依赖 VSCode 的语言服务器机制来注入诊断；但如果你同时启用了 sh（foxundermoon）、Bash Debug 或 Volar（尤其 Vue 项目里开了 Take Over Mode），它们可能偷偷劫持了 shellscript 语言 ID 的语义解析能力，导致 ShellCheck 只能做基础语法扫描，无法识别变量作用域或命令展开。
- 运行
Developer: Show Running Extensions，过滤出含shell、bash、volar的插件，看哪些状态是Activation failed或耗时 >1000ms - 禁用
sh（foxundermoon）和Bash Debug，只留ShellCheck+ 内置@vscode/shell-language-features，测试高亮是否恢复 - Vue 项目中务必检查
"vue.preferences.useVolarForVue3": true是否误启用了 Volar 对.sh的接管（Volar 有时会泛匹配*.*）
检查 editor.defaultFormatter 和 formatOnSave 是否被抢注
语法解析错误常伴随格式化异常：保存后缩进错乱、引号被强制改双引号、$(cmd) 被拆成多行——这说明不止一个插件在响应 editor.formatOnSave，而 VSCode 只会让其中一个真正执行，其余静默失败，连带影响语法树构建。
- 打开
settings.json，搜defaultFormatter，确保只有一个是针对shellscript的，例如："[shellscript]": {"editor.defaultFormatter": "timonwong.shellcheck"} - 禁用所有非 ShellCheck 的格式化插件（如 Prettier、EditorConfig），避免它们注册
onSave钩子干扰语言服务初始化 - 临时关闭
editor.formatOnSave，仅靠ShellCheck: Run ShellCheck手动触发一次，看波浪线是否出现 —— 若出现，说明格式化链路污染了诊断链路
ShellCheck.executablePath 配错会静默禁用语法诊断
路径填错不会报红，只会让 ShellCheck 完全不跑诊断 —— 表现就是：无波浪线、无悬停提示、ShellCheck: Show Output 面板空或只显示 command 'shellcheck.run' not found。
- 终端执行
which shellcheck，复制完整路径（如/opt/homebrew/bin/shellcheck） - 在
settings.json中明确配置："shellcheck.executablePath": "/opt/homebrew/bin/shellcheck" - 不要用
~或环境变量（如$HOME），VSCode 启动方式（桌面图标 vs 终端）会影响变量继承，路径必须绝对且可执行 - 改完后必须重启 VSCode，
ShellCheck: Show Output面板里能看到启动日志才算真正加载成功
真正难排查的不是哪个插件“坏了”，而是它卡在激活阶段却不报错，比如 sh 插件加载超时后残留监听器，持续拦截 textDocument/didOpen 事件，导致 ShellCheck 根本收不到文档内容 —— 这种情况只能靠 Developer: Show Running Extensions 看 Activation Time + code --disable-extensions 对比验证，缺一不可。
