若VSCode调试Shell脚本异常，需依次安装ShellCheck与Bash Debug扩展、配置shellcheck路径、创建launch.json调试配置、设置断点并启动调试、校验shebang及终端默认shell。
如果您在使用 VSCode 编写和调试 Shell 脚本时遇到语法高亮异常、断点不生效或终端执行报错等问题，则可能是由于扩展缺失、配置未启用或调试环境未就绪。以下是解决此问题的步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装 ShellCheck 和相关扩展
ShellCheck 是一个静态分析工具，用于检测 Shell 脚本中的常见错误和潜在问题；VSCode 需通过扩展调用该工具实现实时诊断。同时需安装支持 Shell 语法高亮与调试协议的扩展。
1、打开 VSCode，点击左侧活动栏的扩展图标（或按 Cmd+Shift+X）。
2、在搜索框中输入 ShellCheck，选择由 TimonVS 发布的官方扩展并点击安装。
3、再次搜索 Bash Debug，安装由 rogalmic 提供的调试器扩展。
4、重启 VSCode 使扩展生效。
二、配置 ShellCheck 路径与验证环境
VSCode 默认无法自动定位本地 ShellCheck 可执行文件，需手动指定其安装路径；若未安装 ShellCheck，需先通过包管理器部署。
1、在终端中运行 which shellcheck，确认返回类似 /opt/homebrew/bin/shellcheck 的路径。
2、若命令未找到，执行 brew install shellcheck 安装（macOS）或 sudo apt install shellcheck（Ubuntu）。
3、按下 Cmd+, 打开设置，搜索 shellcheck.executable，点击编辑设置项，在输入框中粘贴上一步获取的完整路径。
三、启用 Bash Debug 启动配置
Bash Debug 扩展依赖 .vscode/launch.json 文件定义调试会话参数，必须为当前工作区创建该配置，否则断点将被忽略。
1、确保已打开包含 .sh 文件的文件夹（而非单个文件），即以文件夹形式打开工作区。
2、按 Cmd+Shift+P，输入 Debug: Open launch.json 并回车。
3、选择环境为 Bash，VSCode 将自动生成模板配置。
4、在生成的 configurations 数组中，确认存在 "type": "bash"、"request": "launch" 和 "program": "${file}" 字段。
四、设置断点并启动调试会话
VSCode 的 Bash 调试器通过注入调试代理在子 shell 中运行脚本，断点仅在脚本实际执行到对应行时触发，需确保脚本具备可执行权限且无语法硬错误。
1、在 Shell 脚本中点击行号左侧空白区域，出现红色圆点即表示断点已设置成功。
2、右键脚本编辑窗口，选择 Run Code 验证是否可正常执行（需先赋予执行权限：chmod +x script.sh）。
3、点击左侧调试图标（或按 Cmd+Shift+D），选择配置名称（如 Bash Launch），再点击绿色三角形启动调试。
4、调试过程中可在“变量”面板查看 $0、$1 等内置参数值，在“调试控制台”中执行 echo $PATH 等命令。
五、修复常见终端执行异常
VSCode 内置终端默认使用 zsh，而部分 Shell 脚本依赖 bash 特性（如 declare -A 关联数组），直接运行可能因解释器不匹配导致语法错误。
1、在脚本首行确认 shebang 是否为 #!/usr/bin/env bash 或 #!/bin/bash，避免使用 #!/bin/sh。
2、按下 Ctrl+` 唤出集成终端，在终端中执行 echo $SHELL，确认当前 shell 类型。
3、若需强制使用 bash 运行，可在终端中输入 bash script.sh 替代直接执行 ./script.sh。
4、在 VSCode 设置中搜索 terminal.integrated.defaultProfile.osx，将其值设为 bash 以统一终端默认解释器。
