必须先查本地VSCode主版本号（如1.90.2→1.90），再比对.vsix中package.json的"engines":{"vscode":"^1.85.0"}，确保本地版本≥插件最低要求，否则静默失败或报不兼容；架构、extensionKind、os等字段也需严格匹配，且安装后须彻底退出VSCode（含托盘进程）才能生效。
查清本地 VSCode 主版本号再动手
离线安装前不确认 code --version 输出的主版本，等于蒙眼装包。VSCode 只取版本字符串前两位（如 1.90.2 → 1.90），跟 .vsix 里 package.json 的 "engines": {"vscode": "^1.85.0"} 做语义化比对：你本地的 1.90 必须 ≥ 插件声明的最低版本（1.85），否则直接静默失败或报 Extension is not compatible。
别信 Help → About 页面显示的完整版号括号内容（比如 (arm64)），那是架构标识，不是版本号；也别看插件市场网页上标“最新版”，得点进 Version History 手动找和你主版本最接近的旧版 .vsix。
改 package.json 中的 engines.vscode 是最快兜底手段
找不到匹配版本的 .vsix？直接改它。用 7-Zip / Archive Utility 或 unzip 打开 .vsix（本质是 zip），定位到 extension/package.json，把 "vscode": "^1.103.0" 改成你本地能接受的范围，比如 "vscode": "=1.90.0" 或宽松点的 "vscode": "^1.85.0"。
- 改完必须重新打包为 zip，再把后缀名改回
.vsix（Windows 别用右键重命名，用 PowerShell：Copy-Item "old.zip" "new.vsix" -Force） - Linux/macOS 下验证是否改成功：
unzip -p your-extension.vsix extension/package.json | grep engines - 改错字段名（比如写成
engine少个s）或格式错（多逗号、缺引号）会导致整个包被拒绝加载，不报错，只静默失效
架构和 extensionKind 不匹配，功能会“消失”而不是报错
ARM Mac 上装 x64 构建的插件（尤其是含 native binary 的，比如 pyright、volar-server），VSCode 不会弹错，但语言服务压根不启动——状态栏卡在 “Initializing…”、Output 面板空空如也、补全/跳转全部失灵。
同样，"extensionKind": ["ui"] 的插件在 Remote-SSH 场景下不会激活，除非显式声明 ["ui", "workspace"]；而 "os": ["win32"] 的插件在 macOS/Linux 上根本不会解压到扩展目录。
验证方式统一：unzip -p your-extension.vsix extension/package.json | grep -E "(engines|os|extensionKind)"，对照你当前环境逐项核对。
装完不重启、不退出托盘进程，等于没装
VSCode 的插件系统靠 Extension Host 进程加载，这个进程不会热更新。哪怕你用 code --install-extension 成功返回，或者拖拽提示“已安装”，只要没彻底退出 VSCode（包括右下角系统托盘里的进程），新插件就不会进入激活状态。
更隐蔽的是 Remote-SSH 场景：插件装在本地，但 Python/TypeScript 语言服务实际运行在远端服务器上。此时必须确保远端 $HOME/.vscode-server/extensions/ 目录里有对应扩展的完整文件夹（含 node_modules 和二进制可执行文件），不能只拷 .vsix 文件过去。
常见误操作：
- 点完“安装”就立刻打开项目——没用，得关窗口、杀托盘、再开
- 远程连接未建立就往本地 extensions 目录扔文件——远端根本看不到
- 以为装了
ms-python.python就自动带pyright——其实首次启用才下载，离线必须提前在有网机器上触发一次完整加载，再整目录迁移
最易被忽略的点：所有校验都通过、插件也显示已启用，但 Prettier 按保存没反应，Python 补全不出现——大概率不是版本问题，而是 .prettierrc.json5 缺失，或远端没部署 pyright-server 二进制。离线环境里，“装上”和“能用”之间隔着三道手动补全的坎。
