必须安装shellcheck CLI并配置VSCode扩展：macOS用brew install shellcheck，Ubuntu用sudo apt install shellcheck，Windows推荐WSL2；终端验证shellcheck --version后重启VSCode，配合timonwong.shellcheck扩展即可实现实时语法检查与安全提示。
VSCode 写 Shell 脚本完全可行，但默认不带语法检查和安全提示，shellcheck 是目前最可靠、最易集成的 Lint 工具，必须装；直接按 F5 运行脚本默认走的是 Node.js 调试器，会报错，得手动配 launch.json 或用终端运行。
怎么装 shellcheck 并让 VSCode 识别它
VSCode 本身不内置 Shell Lint，靠扩展 + 外部命令协同工作。核心是装好 shellcheck CLI，并确保 VSCode 的 ShellCheck 扩展能调到它。
- macOS：用
brew install shellcheck（别用npm install -g shellcheck，那个是假的） - Ubuntu/Debian：
sudo apt install shellcheck - Windows：推荐用 WSL2 安装，或从 GitHub releases 下载预编译二进制，加进
PATH - 装完在终端跑
shellcheck --version确认可用；VSCode 重启后，配合ShellCheck扩展（作者是timonwong），就能实时标出echo $HOME漏引号、未声明变量等典型问题
为什么 Shell 脚本 F5 运行失败？怎么配 launch.json
VSCode 默认调试器不认识 .sh 文件，F5 会弹“无法找到启动程序”，不是配置错了，是根本没告诉它“用什么执行”。要运行，就得显式指定解释器路径和参数。
- 项目根目录建
.vscode/launch.json - 写入以下最小配置（注意
program必须是绝对路径或${file}，不能写./script.sh）：
{
"version": "0.2.0",
"configurations": [
{
"type": "shellscript",
"request": "launch",
"name": "Run Shell Script",
"program": "${file}",
"args": [],
"console": "integratedTerminal"
}
]
}
- 需要
shellscript类型支持 → 安装扩展Shell Script（作者foxundermoon），否则type: "shellscript"不生效 - 如果只希望快速测试，更轻量的做法是：右键脚本 → “Run Code”（需装
Code Runner扩展），并在设置里把code-runner.executorMap中shell对应值设为bash -e（-e让出错即停，比默认sh更贴近实际部署行为）
常见误配导致 Lint 不生效或报奇怪错误
Lint 看似开了，但没提示，或者提示一堆无关警告，大概率是 Shell 类型声明不对或 shebang 冲突。
- 文件开头没写 shebang（如
#!/bin/bash或#!/usr/bin/env bash），shellcheck默认按sh解析，遇到[[或$(( ))就报错；补上明确 shebang 可解决 - VSCode 底部状态栏显示语言模式是
Shell Script，但点开选成了Bash或Shell—— 二者解析规则不同，Shell模式下shellcheck仍按 POSIX sh 检查，容易误报；建议统一设为Bash（通过命令面板Change Language Mode） -
shellcheck版本太老（如 Ubuntu 20.04 自带的 0.4.6），对declare -A或mapfile支持差；升级到 0.9+ 能显著减少误报 - 脚本里用了
source ./lib.sh，但lib.sh不在当前目录或没加执行权限，shellcheck不报错但运行时崩 —— Lint 只静态分析，不校验文件存在性，这点容易被忽略
真正麻烦的不是配不配得出来，而是不同发行版的 shellcheck 行为差异、shebang 和语言模式的隐式耦合、以及 Lint 和运行时环境不一致带来的“看着绿灯却跑挂”——这些得一个个对着 shellcheck -x 输出和实际 bash -n 校验才能排掉。
