ShellCheck插件未生效需依次检查：安装启用、文件关联、shellcheck二进制路径、shell类型匹配、保存触发设置及诊断输出。
ShellCheck 插件没生效？先确认安装和启用状态
VSCode 默认不带 ShellCheck，必须手动装插件且确保它被激活。很多人装完就以为万事大吉，结果写错 if [ $var = "x" ]; 也没提示——其实是插件根本没跑起来。
- 打开扩展市场，搜
ShellCheck，认准作者是timonwong（官方维护） - 安装后重启 VSCode（部分版本不重启不加载语言服务器）
- 打开一个
.sh文件，看右下角状态栏是否显示ShellCheck；没显示说明未激活，检查文件关联：右键 →Change Language Mode→ 选Shell Script - 如果已选 Shell Script 但依然无提示，运行
ShellCheck: Show Output（Ctrl+Shift+P 输入该命令），看有没有报错如command 'shellcheck.run' not found——大概率是插件没正确启动
ShellCheck 找不到？检查 PATH 和二进制路径配置
插件本身只是个壳，真正干活的是本地的 shellcheck 可执行文件。Windows 用户常卡在这步：WSL 里装了 shellcheck，但 VSCode 在 Windows 下运行，根本访问不到 WSL 的 PATH。
- 在终端运行
which shellcheck（macOS/Linux）或where shellcheck（Windows CMD）确认是否可执行 - 如果没安装，用包管理器装：
brew install shellcheck（macOS）、sudo apt install shellcheck（Ubuntu）、choco install shellcheck（Windows） - VSCode 插件默认从系统 PATH 查找，若你用 nvm/pnpm/asdf 等工具管理环境，可能 PATH 不一致；这时需在 VSCode 设置中显式指定：
shellcheck.executablePath设为完整路径，例如/usr/local/bin/shellcheck - 注意：WSL 用户若在 Windows 版 VSCode 中编辑 WSL 文件，建议直接使用
Remote - WSL扩展，否则路径、编码、换行符都容易出问题
提示不出现或误报太多？调整 ShellCheck 的 shell 类型和检查级别
ShellCheck 默认按 bash 解析，但你的脚本可能是 sh、zsh 或 dash，类型不匹配会导致大量误报（比如 [[ 在 sh 下直接标红）。
- 在脚本第一行加正确的 shebang，例如
#!/bin/bash或#!/usr/bin/env sh，ShellCheck 会据此推断目标 shell - 如果 shebang 缺失或模糊，可在 VSCode 设置中强制指定：
shellcheck.shell设为bash/sh/zsh - 某些警告（如
SC2086：未引号变量展开）属于风格建议，默认开启；若想只看硬性错误，修改shellcheck.enable并配合shellcheck.additionalArgs加["-e", "SC2086", "-e", "SC2154"]屏蔽特定码 - 注意：屏蔽规则只影响当前工作区，别误删成全局设置，否则团队协作时别人看不到关键提示
保存时不自动检查？补上保存触发和诊断输出开关
ShellCheck 默认是“打开文件时扫描 + 编辑时增量检查”，但很多人习惯写完保存才看结果，而默认设置并不在保存时强制重跑——这就导致改完忘保存，错误一直挂着没清掉。
- 开启保存时检查：
shellcheck.onSave设为true（默认是false） - 遇到提示不更新？打开命令面板，运行
ShellCheck: Restart Server，比关插件再开更可靠 - 诊断信息藏得深：打开
Output面板（Ctrl+Shift+U），下拉选ShellCheck，能看到每次分析的原始命令、返回码和 stderr，比如Failed to parse file: Parse error就说明语法太烂，连 ShellCheck 都读不下去 - 特别注意：如果脚本里有
source引入其他文件，而那些文件路径不对或权限不足，ShellCheck 会静默跳过部分检查——它不会报错，但提示变少，容易误判为“没问题”
ShellCheck 的提示不是万能的，它依赖准确的 shell 类型、可执行路径和干净的语法上下文。最常被忽略的是 shebang 缺失和 WSL/Windows 路径混用，这两点一错，整个分析链就断了。
