直接看插件目录下package.json中的engines.vscode字段最准，它是VSCode启动时硬性校验的依据；需对照code --version输出版本判断是否满足语义化约束，如^1.76.0表示兼容1.76.0至2.0.0前所有版本。
直接看 package.json 里的 engines.vscode 字段，比市场页面或 UI 显示更准——它才是 VSCode 启动时真正校验的依据。
怎么看插件实际声明的 VSCode 版本范围
插件是否兼容，不取决于你装的是哪个版本，而取决于它自己在 package.json 中写的 engines.vscode。这个字段是 VSCode 启动加载时硬性检查的门槛，UI 上显示“已安装”可能只是缓存或滞后状态。
- 找到插件目录：Windows 是
%USERPROFILE%\.vscode\extensions\{publisher}.{name}-{version}，macOS/Linux 是~/.vscode/extensions/{publisher}.{name}-{version} - 打开该目录下的
package.json，搜索"engines"字段，重点关注"vscode": "^1.76.0"这类值 - 对照你当前 VSCode 版本（终端执行
code --version），判断是否满足语义化约束：比如^1.76.0表示支持1.76.0到2.0.0之前的所有版本
为什么 code --list-extensions --show-versions 不够用
这条命令只告诉你“装了什么版本”，但完全不反映兼容性。它甚至不会报错，哪怕插件的 engines.vscode 写的是 =1.90.0 而你用的是 1.85.0——VSCode 会静默跳过激活，插件图标灰掉、功能全失，但命令输出里依然照常列出。
- 典型现象：插件详情页右下角显示版本号，但点开后提示 “This extension is disabled due to compatibility issues”
- 此时必须进插件目录查
package.json，不能信 UI 或命令行列表 - 如果插件根本没出现在
Developer: Show Running Extensions列表中，大概率就是engines.vscode校验失败被拒载
离线安装 .vsix 时提示“版本不兼容”怎么办
不是插件真不兼容，而是它的 package.json 没适配你当前 VSCode。手动改是最直接解法，但要注意改完必须重新打包为 .vsix，不能只改解压后的文件。
- 用 ZIP 工具打开 .vsix 文件（它本质是 zip 包）
- 定位到根目录下的
package.json，修改engines.vscode字段，例如从"^1.92.0"改成"^1.85.0" - 保存后重新压缩为 ZIP，再把后缀名改回
.vsix（注意：必须用 ZIP 标准压缩，不能用 RAR/7z；路径名不能含中文或空格） - 执行
code --install-extension /path/to/fixed.extension.vsix安装
自动更新导致兼容性突然失效的隐藏原因
你以为禁用了自动更新就安全了？不一定。有些插件默认开启预发布通道（pre-release），它的版本号如 10.0.0-pre.1 会被认为“高于”你手动装的 9.10.3，结果一小时后就被覆盖——而新版本的 engines.vscode 可能已升到 ^1.95.0，你的 VSCode 就直接失联。
- 务必关闭预发布：插件详情页右上角 ⋯ → 取消勾选
Switch to Pre-release Version - 确认设置中
extensions.autoUpdate为false - 装完旧版后，立刻进插件目录核对
package.json的version和engines.vscode是否真为你想要的值——别信 UI 显示
最易被忽略的一点：VSCode 对 engines.vscode 的校验发生在 Extension Host 启动阶段，且不提供友好提示。一旦不匹配，插件就彻底“隐身”，连错误日志都未必出现。所以排查兼容性问题，永远优先钻进 package.json，而不是反复重装或调设置。
