VSCode版本兼容性异常由engines.vscode字段硬性拦截导致，需用code --version获取精确版本（如1.80.2），再解压.vsix查extension/package.json中的engines.vscode声明，二者必须对齐。
VSCode 版本兼容性异常不是随机发生的，而是插件、语言服务或远程组件在启动/安装阶段被 engines.vscode 字段硬性拦截的结果。只要看到 “not compatible with VS Code '1.xx.x'” 或 “requires a newer version” 这类提示，就说明校验已失败，无需怀疑配置或网络——直接查版本对齐关系。
怎么看当前 VS Code 实际版本号
别信 About 窗口里模糊的“最新版”描述，必须拿到精确语义化版本字符串。终端执行 code --version 是最可靠方式，输出第一行就是真实主版本，例如 1.80.2。Windows 用户若提示 command not found，请先检查 VS Code 是否勾选了「Add to PATH」（安装时或设置里可补）；macOS/Linux 用户确认 /usr/local/bin/code 存在且指向正确二进制。
- 菜单 Help → About 显示的版本可能被 UI 缓存延迟，尤其升级后未完全退出时
- 命令面板里输入 Developer: Show Running Extensions，顶部状态栏也会显示版本，但不如终端输出权威
- 远程开发场景下，
code --version查的是本地，远端~/.vscode-server目录里的版本需单独 ssh 进去查，两者必须一致
怎么查插件到底要求什么版本
插件的 engines.vscode 声明藏在 package.json 里，但位置容易找错：不是 vsix 根目录那个，而是解压后 extension/package.json 中的字段。.vsix 本质是 zip，用 unzip -l xxx.vsix | grep package.json 可快速定位路径。
- 离线安装失败时，必须解压 vsix 查这个字段；市场页面显示的 Compatibility 区域只是作者声明，不一定和你下载的 vsix 一致
- 已安装但被禁用的插件，路径在
~/.vscode/extensions/作者名.插件名-版本号/下，直接编辑该目录内的package.json - 注意语义化写法差异：
"^1.85.0"表示 ≥1.85.0 且 ">=1.85.0 才能跨多个主版本，盲目改成=1.85.0会导致 minor 更新（如 1.85.1）也被拒绝
Remote-SSH 连接卡在 Starting VS Code Server 怎么办
这不是插件问题，是本地 VS Code 主程序和远端自动部署的 vscode-server 二进制不匹配。VS Code 会根据本地版本号拉取对应 commit 的 server，一旦远端已有旧版 server，它不会覆盖，而是死等或报 hash 不一致。
- 先确认本地版本：
code --version输出如1.102.3，则远端~/.vscode-server/bin/下必须存在对应 commit ID 的目录 - 最简验证：ssh 登录远端，运行
rm -rf ~/.vscode-server，再重连，VS Code 会强制重下匹配版本 - 若远端无法联网，需手动下载对应 commit 的 server tarball（URL 格式为
https://update.code.visualstudio.com/commit:<commit-id>/server-linux-x64/stable</commit-id>），传上去解压
改完 engines 还不生效？重点检查三件事
改了 package.json 却没反应，大概率不是改错了，而是 VS Code 缓存或加载机制没触发。不要反复重启，先做这三步：
- 确保修改的是正在使用的插件目录（
~/.vscode/extensions/xxx），而不是随便找个同名文件夹改 - 改完后必须完全退出 VS Code（包括托盘进程），macOS/Linux 还要检查
ps aux | grep code是否还有残留 extensionHost 进程 - 如果插件依赖
node_modules，改完engines后删掉该目录再重装依赖（npm install），否则旧缓存可能仍引用被移除的 API
真正难处理的从来不是版本数字本身，而是插件代码里悄悄调用了某个已废弃的 API——比如 workspace.findFiles 的 useGitIgnore 参数在 1.102+ 被移除。这种时候改 engines 只能绕过安装检查，运行时报 TypeError 才是真问题。所以优先查插件 GitHub 的 Issues 和 Releases，看是否已有适配补丁。
