插件离线安装失败因VS Code版本低于engines.vscode要求，需解压.vsix查看extension/package.json中"engines": {"vscode": "^1.103.0"}，本地code --version版本须≥1.103.0。
怎么看插件包要求的 VS Code 最低版本
离线安装失败时弹出 Unable to install extension 'xxx' as it is not compatible with VS Code '1.xx.x'，核心就是 engines.vscode 字段不匹配。这个字段藏在 .vsix 包里，不是市场页面写的“Compatible with 1.80+”，而是真实生效的硬约束。
把 .vsix 当作普通 zip 解压（后缀改 .zip 或用 unzip -l plugin.vsix），进 extension/package.json 找这一行：
"engines": { "vscode": "^1.103.0" }
你本地运行 code --version 输出的版本（如 1.85.2）必须 ≥ 这个值。注意：^1.103.0 表示 ≥1.103.0 且
- 别信插件市场页面的兼容性描述，只认
package.json里的engines.vscode - Windows 上右键重命名改后缀可能损坏文件头，建议用 PowerShell 的
Copy-Item或命令行mv -
unzip -t plugin.vsix必须返回OK，否则连解析package.json都会失败
怎么安全降级 engines.vscode 字段
内网机器不能升级 VS Code，就只能调低插件包的版本门槛。直接改 package.json 是最快路径，但有风险点必须控制：
- 把
"^1.103.0"改成">=1.85.0 比改成 <code>"=1.85.0"更稳妥——保留小版本弹性，避免后续补丁冲突 - 改完必须用原工具重新打包为 zip，再手动改后缀回
.vsix；用压缩软件“另存为”或“保存”会写入额外元数据，导致签名失效 - Linux/macOS 下推荐用命令行：
zip -r fixed.vsix extension/（确保当前目录含解压后的extension/文件夹） - 改完不验证就装？先跑
unzip -p fixed.vsix extension/package.json | grep engines确认改对了
为什么改了还是装不上：签名和 PATH 常被忽略
即使 engines.vscode 匹配了，离线安装仍可能静默失败，两个底层卡点最常漏查：
-
INVALID_SIGNATURE错误：离线环境无法连接微软证书服务器校验签名，图形界面安装不提示，命令行必须加--allow-unverified参数，例如：code --install-extension python-2024.10.0.vsix --allow-unverified -
command not found: code：VS Code 官方 deb/rpm 包默认不加code到PATH，尤其在 SSH 终端或虚拟机里。运行which code验证，无输出就去设置里执行Shell Command: Install 'code' command in PATH - 装完不生效？不是没装上，而是 VS Code 进程没彻底退出——右下角托盘图标也要右键退出，否则缓存不刷新
装上了但功能异常：依赖和二进制才是真坑
很多插件（比如 ms-python.python、ms-vscode.cpptools）只是“壳”，真正干活的组件根本不在 .vsix 里：
- Python 插件首次打开
.py文件会拉pyright语言服务器，离线时卡在状态栏 “Downloading…”——必须在联网机器上触发一次完整加载，再拷整个$HOME/.vscode/extensions/ms-python.python-xxx/目录过去 - C/C++ 插件的
cpptools-srv是预编译二进制，严格绑定node.js abi版本（查法：process.versions.modules在 VS Code DevTools 里执行），x64 机器装了 arm64 构建的 vsix 就会报cannot find module 'node.exe' - 依赖插件（如
esbenp.prettier-vscode依赖bradlc.vscode-tailwindcss）不会自动装，得看extensionDependencies字段，手动补全
离线部署真正的复杂点不在“改个版本号”，而在于确认 engines.vscode、绕过签名、补全依赖、迁移 native 二进制这四层都对齐——少一环，插件就只是列表里一个灰色图标。
