断点需在vscode启动调试后才生效，必须配置正确launch.json（type为"bash"）、安装bashdb、指定绝对路径program、使用独立进程执行脚本。
断点本身不生效，因为没走调试协议
VSCode 里点行号左边加个红点，只是“标记位置”，不是“启动调试”。F5 按下前，脚本照常执行，断点完全被忽略。必须打开“运行和调试”侧边栏（Ctrl+Shift+D），选中一个有效配置，再点 ▶️ 启动——否则所有断点都是摆设。
常见现象：红点是实心的 ✅，但脚本一跑就过，不停；或者红点是空心的 ❌，说明 launch.json 没加载或 type 配错。检查 launch.json 中 "type" 字段是否为 "bash"（大小写敏感），不是 "shell"、"sh" 或留空。
调试器找不到 bashdb，得自己装并配对路径
bashdb 不是 VSCode 自带的，也不是 Bash 内置命令。它是独立工具，Bash Debug 插件只是 UI 封装，底层全靠它驱动。没装就报 “command not found” 或直接静默失败。
- Linux/macOS：运行
sudo apt install bashdb（Ubuntu）或brew install bashdb（macOS） - 装完验证：
bashdb --version能输出版本号才算成功 - VSCode 中按
Cmd+Shift+P输入 “Shell Script: Configure Shell Interpreter”，选中你系统里真实的bash路径（如/bin/bash或/opt/homebrew/bin/bash） - 确保
launch.json的"program"指向可执行脚本绝对路径，且该脚本有#!/usr/bin/env bash和chmod +x
launch.json 配置不对，断点永远进不去
VSCode 的 Bash 调试严重依赖 launch.json 里三个字段精准匹配：解释器路径、脚本路径、工作目录。任一出错，调试器连进程都起不来。
正确示例（放在项目根目录 .vscode/launch.json）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Bash Debug",
"type": "bash",
"request": "launch",
"program": "${workspaceFolder}/deploy.sh",
"args": [],
"cwd": "${workspaceFolder}",
"env": { "PATH": "/usr/bin:/bin:/usr/local/bin" }
}
]
}
-
"program"必须是脚本的绝对路径（用变量表达），不能是./deploy.sh或deploy.sh -
"cwd"影响source、相对路径读写，建议统一设为${workspaceFolder} - 如果脚本依赖
~/.bashrc里的函数或别名，得在env里补全 PATH，或改用终端手动跑bash -i deploy.sh更可控
ShellCheck 报错干扰判断，别让它误导你关掉断点
ShellCheck 默认按 POSIX 标准检查，看到 [[ ]]、$FUNCNAME、数组就标黄“未声明变量”，但这不是语法错误，只是它不知道你目标是 Bash。这类警告不影响断点行为，但容易让人误以为“脚本有错所以调不了”。
解决办法很直接：
- VSCode 设置里搜
shellcheck，把ShellCheck: Shell选项设为bash（不是sh或空） - 本地确认已安装：
shellcheck --version，没装就补上 - 别信插件提示的“disable all”，真正危险的是不加引号的变量展开（如
echo $HOME），那才是 word splitting 真问题
最常被忽略的一点：断点只在 Bash 解释器逐行解析时才可能命中。如果你用 source script.sh 在当前 shell 执行，调试器根本不会介入——必须是独立进程，也就是 bash deploy.sh 或 ./deploy.sh 这种方式启动。
