VS Code升级后插件失效、Remote-SSH卡住、原生模块报错的根源是engines.vscode声明、process.versions.napi版本、远端vscode-server二进制三者未对齐;升级前须禁用自动更新、备份扩展列表并清理插件目录。

直接锁定关键变量,比事后救火更省力:VSCode 升级后 90% 的插件失效、Remote-SSH 卡住、原生模块报错,根源不是插件坏了,而是 engines.vscode 声明、process.versions.napi 版本、远端 vscode-server 二进制三者之一没对齐。
升级前必须禁用自动更新并备份扩展列表
VSCode 不支持“回退式升级”,所谓降级本质是卸载重装。一旦自动更新触发,旧版配置和兼容插件可能被覆盖或静默禁用。
- 打开设置(
Ctrl+,),搜索update.mode,设为none或manual;确认该值已写入settings.json且未被注释 - 导出当前设置:
Ctrl+Shift+P→Preferences: Export Settings - 记录已装扩展:
code --list-extensions > extensions.txt,降级后可用code --install-extension批量重装 - 别跳过清理:
~/.vscode/extensions/(Linux/macOS)或%USERPROFILE%\.vscode\extensions\(Windows)建议先重命名为extensions-backup,让新版启动时重建干净目录
插件报 “not compatible with VS Code x.x.x” 怎么办
这是 engines.vscode 字段硬拦截的明确信号,不是网络或权限问题。市场页面默认不展示旧版,但可强制调出。
- 打开插件市场页(如
https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode),在 URL 末尾加?vscodeVersion=1.104.2(替换成你本地code --version输出的精确版本) - 刷新后右下角出现
Install Another Version…下拉菜单,只选带绿色 ✅ 的版本 - 若菜单灰显,说明作者未发布该版本兼容包,需走离线路径:下载 .vsix → 用 7-Zip /
unzip解压 → 编辑extension/package.json中的"vscode"值(例如改为">=1.85.0")→ 重新打包为 zip → 改后缀为 .vsix → 用命令面板安装
Remote-SSH 连接卡在 “Starting VS Code Server”
这不是前端插件问题,而是远端 vscode-server 二进制与本地主程序版本不一致。Remote-SSH 插件本身只是遥控器,真正干活的是远端那个 server。
- 本地运行
code --version,记下完整版本号(如1.104.2) - 登录远端机器,执行
rm -rf ~/.vscode-server(注意:不是~/.vscode-server-bin) - 重连 SSH,VSCode 会自动拉取匹配版本的 server;若仍失败,检查远端
~/.vscode-server/bin/下的子目录名是否与本地版本哈希一致 - 企业环境若用 Remote-Containers,同理要确保远端容器内
vscode-server版本与本地严格一致
终端里 node --version 还是旧的,或插件报 Cannot find module './build/Release/xxx.node'
VSCode 启动时固化 shell 环境快照,nvm use 切换后主进程不会自动刷新 PATH;而原生模块报错几乎全是 napi_build_version 错位——比如 VSCode 1.90+ 内置 Node.js 22.4.0,process.versions.napi === '9',但你用 Node.js v20.x(napi=8)跑了 npm rebuild。
- 彻底退出 VSCode:Windows 结束所有
Code.exe进程;macOS Dock 右键 Quit;Linux 执行code --no-sandbox --disable-gpu - 验证终端环境:
which node应输出~/.nvm/versions/node/vxx.x.x/bin/node,否则重启无效 - 重编译原生模块必须带全参数:
npm rebuild --napi-build-version=9 --runtime=electron --target=34.0.0 - 清空插件目录下的
node_modules/.pnpm和out/,否则旧缓存会被优先加载
最易被忽略的是:ABI 兼容性不看 process.version,只认 process.versions.napi;Remote-SSH 的远端 server 版本必须和本地 code --version 完全一致;改完 engines.vscode 后不执行 Developer: Reload Window,改等于白改。


















