插件失效、原生模块报错、Remote-SSH连不上，主因是engines.vscode不匹配或napi_build_version错位；需查Disabled列表、控制台报错及process.versions.napi值，再安装适配版本或用VSCode内置Node重编译。
VSCode 升级后插件失效、原生模块报错、Remote-SSH 连不上——这些问题几乎都不是“坏了”，而是 engines.vscode 声明不匹配或 napi_build_version 错位导致的主动拦截。直接重启或重装插件没用，得对准这两个关键点动手。
怎么快速确认是 engines.vscode 版本不匹配
打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P），输入 Extensions: Show Installed Extensions，右上角筛选器选 Disabled。如果插件列在这里，且详情页顶部明确写着 Disabled，基本就是 engines.vscode 不满足。
- 控制台（
Help → Toggle Developer Tools → Console）里常出现红字：Extension 'ms-python.python' is not compatible with Code '1.102.3' - 插件卡片右上角齿轮菜单若显示
Disable (For All Workspaces)，但你没手动点过，说明是 VSCode 自动禁用的 - 别信状态栏图标——它可能只是 UI 残留；按
Ctrl+Shift+P输插件命令（比如prettier.format）看是否报command 'prettier.format' not found
安装匹配当前 VSCode 版本的插件旧版
扩展面板里点插件右下角 ⋯ → Install Another Version…，选一个和你当前 code --version 输出完全匹配的历史版本。这个操作比改 .vsix 安全、省事，且保留市场签名验证。
- 高频出问题的插件：
ms-python.python、esbenp.prettier-vscode、ms-vscode-remote.remote-ssh，它们在 1.102+ 后对引擎限制明显变严 - 如果该选项灰显，说明插件作者未发布历史版本；此时需手动下载
.vsix文件再安装 -
Remote-SSH类插件还要注意远端~/.vscode-server版本必须和本地主程序一致，否则连接卡在Starting VS Code Server；可先rm -rf ~/.vscode-server再重连
原生模块报 Cannot find module './build/Release/xxx.node' 怎么修
这是 ABI 不兼容的典型错误，常见于 VSCode 1.90+（内置 Node.js 22.4.0，napi_build_version=9），而你用系统 Node.js v20.x（napi=8）执行了 npm rebuild，生成的二进制无法被加载。
- 先验证：在 VSCode 开发者工具控制台运行
process.versions.napi，对比终端里node -p "process.versions.napi"的输出。若不一致（比如终端是 8，扩展主机是 9），就是 ABI 错位 - 重编译必须用 VSCode 内置 Node 执行：
npm rebuild --napi-build-version=9 --runtime=electron --target=34.0.0 - 必须清空插件目录下的
node_modules/.pnpm和out/，否则旧缓存优先被加载 - 别只看
process.version，napi_build_version才是关键
手动修改 .vsix 或已安装插件的 engines 字段
离线场景或 Marketplace 无可用旧版时，需解包 .vsix 并改 extension/package.json 中的 engines.vscode 字段。注意不是外层的 package.json。
- 用 7-Zip（Windows）、Archive Utility（macOS）或
unzip（Linux）打开.vsix - 定位到根目录下
extension/package.json，把"engines": { "vscode": "^1.103.0" }改为"vscode": ">=1.85.0 这类宽松范围 - 保存后重新打包为 zip，再把后缀名改回
.vsix，最后用Extensions: Install from VSIX命令安装 - 已安装插件可直接编辑本地目录下的
package.json，但改完必须执行Developer: Reload Window，且 VSCode 更新后该值会被自动重置
最易被忽略的是 Remote-SSH 的远端 vscode-server 版本，它和本地 VSCode 主版本必须严格一致；还有插件目录残留的旧构建产物，哪怕只是 out/ 多一个文件，都可能导致静默失败。
