vscode默认不识别.sh文件，必须配置"files.associations": {"*.sh": "shellscript"}，否则始终显示“plain text”，导致高亮、跳转、检查、调试全部失效；临时可点击右下角选shell script，永久需修改settings.json。
没配 files.associations，.sh 文件永远是 Plain Text —— 后续所有高亮、跳转、检查、调试全失效。
为什么 .sh 文件打开显示 “Plain Text”
VSCode 不靠后缀名识别语言，只认 language ID。没配置关联，它就当纯文本处理，连基础高亮都没有。
- 临时解决：点击右下角语言标签 → 选
Shell Script（或Bash） - 永久生效：在
settings.json中加这一行："files.associations": {"*.sh": "shellscript"} - 如果脚本没后缀（比如
deploy或build），单独加："deploy": "shellscript" - 装了
Shell Format、Shell Launcher这类插件？它们不改语言识别逻辑，对高亮无效
语法高亮和智能提示起不来
光装插件不够，bash-language-server 必须装且能被 VSCode 找到，否则补全、跳转、悬停诊断全挂掉。
- 终端运行
bash-language-server --version确认已安装（npm install -g bash-language-server） - 确保它在系统
PATH中；VSCode 启动时若没读到 PATH，LSP 就不会启动 - 打开开发者工具（
Ctrl+Shift+P→Developer: Toggle Developer Tools），Console 里搜bash-language-server看有无报错 -
source引入的变量/函数不会出现在补全里 —— 这是设计限制，不是配置问题
ShellCheck 总是误报 $PWD、local var=1 等合法 Bash 语法
ShellCheck 默认按 POSIX sh 检查，而你写的明明是 Bash 脚本。它把 Bash 特性当“兼容性风险”标红。
- 脚本首行必须有明确 shebang：
#!/usr/bin/env bash（比#!/bin/bash更兼容） - 在
settings.json中强制指定："shellcheck.shell": "bash" - 仍报
SC2034/SC2155？检查文件是否已保存、shebang 是否被其他插件劫持语言模式 - 别用
-e SC2086全局屏蔽未引号变量警告 —— 那是真 bug 高发区，该修就得修
F5 调试报 “bashdb not found”
VSCode 自带调试器不支持 Bash，bash-debug 只是桥梁，真正干活的是系统级 bashdb 工具。路径、权限、PATH 任一环节断掉都会卡住。
- 终端执行
bashdb --version确认已安装（macOS：brew install bashdb；Ubuntu：sudo apt install bashdb） - 运行
which bashdb拿到绝对路径，例如/opt/homebrew/bin/bashdb - 在
.vscode/launch.json的调试配置中显式写死："bashdbPath": "/opt/homebrew/bin/bashdb" - 确保装的是
rogalmic.bash-debug（不是已停更的le0pard.bash-debug），且"type": "bashdb"匹配
最容易被忽略的点：bash-language-server 和 shellcheck 都依赖 VSCode 启动时正确加载系统 PATH。从桌面图标启动 VSCode 时，macOS 和某些 Linux 桌面环境常会丢失 shell 的 PATH，导致这两个工具静默失败 —— 此时必须从终端执行 code . 启动编辑器。
