关键看三处：主版本号必须一致（如1.90.2不可装仅兼容1.87的插件）、架构匹配（help→about中arm64/x64需与下载页“supported platforms”一致）、package.json中"engines":{"vscode":"..."}声明的最小支持版本须≤当前vscode版本。
怎么确认 vsix 文件和当前 VSCode 兼容
不兼容的 .vsix 安装时会静默失败或报错 Extension is not compatible with Code，但 VSCode 很少明确告诉你差在哪。关键看三处：
- 主版本号必须一致：比如你用的是
1.90.2，就不能装标称支持^1.85.0但实际编译于1.87的旧版插件（尤其 Pylance、Jupyter 这类语言服务） - 架构必须匹配：Help → About 里括号中的
arm64、x64或ia32，和下载页面显示的 “Supported Platforms” 对不上就装不了 - 打开
.vsix文件（用unzip -p extension.vsix package.json | grep vscode），检查"engines": {"vscode": "..."}字段是否覆盖你当前版本——注意是“最小支持版本”，不是“最高兼容版本”
命令行安装 vsix 比图形界面更可靠的原因
图形界面（Extensions → … → Install from VSIX）在企业内网、权限受限或路径含空格/中文时容易卡住、无提示、甚至假成功。而 code --install-extension 是唯一走底层扩展注册流程的入口：
- 它直接触发解压 + 写入
extensions/目录 + 更新注册表，不依赖 Marketplace API - 错误信息直接输出到终端：
ENOENT表示路径错，EACCES表示没写入权限，EPERM常见于 Windows 杀软拦截 - Windows 下路径必须用双引号包裹，且推荐正斜杠：
code --install-extension "C:/ext/ms-python.python-2024.6.0.vsix" - 加
--force可覆盖同名旧版，但会清空用户配置（如 Python 解释器路径），慎用
手动复制 vsix 到 extensions 目录为什么总不生效
这是离线安装里最常踩的坑：把 .vsix 文件直接扔进 %USERPROFILE%\.vscode\extensions\（Windows）或 $HOME/.vscode/extensions/（macOS/Linux）根本没用。
- VSCode 启动时只扫描该目录下的**子文件夹**，每个子文件夹名必须是
publishername.extensionname-version格式（如ms-python.python-2024.6.0） - 正确做法是先解压：
unzip extension.vsix -d ms-python.python-2024.6.0，再把整个解压出的文件夹移进去 - 移动后必须完全退出 VSCode（包括托盘进程），否则缓存不会重载新扩展
- 验证是否加载成功：按
Ctrl+Shift+P输入Developer: Show Running Extensions，状态应为Local而非Uninstalled
Python 类插件离线安装要特别注意依赖链
像 ms-python.python 实际是壳，真正干活的是 ms-python.pylance 和 ms-python.vscode-pytest 等。离线时漏掉任一依赖，Python 语法高亮、跳转、补全都会残缺。
- 进 Marketplace 页面，点右上角
Dependencies标签页，把列出的所有.vsix全部下载 - 安装顺序有要求：先装依赖项（如
ms-python.pylance），再装主插件（ms-python.python） - 某些插件（如 Jupyter）还依赖
ms-toolsai.jupyter和ms-toolsai.jupyter-keymap，缺一个就无法启动内核 - 装完重启后，打开
.py文件，看右下角状态栏是否显示 Python 解释器路径和 Pylance 版本 —— 这比“已安装”列表更真实
dbaeumer.vscode-eslint 依赖的 Node.js 运行时没在离线环境里配好。离线部署的本质，是把一套在线自动完成的依赖解析和版本协商过程，手动拆解、对齐、验证。
