确认.vsix与vscode兼容需核对三处：主版本号一致（如1.90.2≥package.json中engines.vscode字段值）、架构匹配（help→about中arm64/x64与下载页“supported platforms”一致）、依赖插件完整安装（查extensiondependencies字段），否则静默失效。
离线安装 VSCode 插件失败，八成不是插件坏了，而是版本、路径或依赖没对上——直接用 code --install-extension 加绝对路径，再配合 package.json 里 "engines": {"vscode": "..."} 字段核对最低版本，能避开 90% 的静默失败。
怎么确认 .vsix 和当前 VSCode 兼容
VSCode 不兼容时几乎不报错，只跳过加载。关键看三处：
- 主版本号必须一致：比如你运行的是
1.90.2，就不能装标称支持^1.85.0但实际编译于1.87的旧版插件（Pylance、Jupyter 尤其敏感） - 架构必须匹配：Help → About 中显示的
arm64/x64，得和下载页 “Supported Platforms” 完全一致；ARM Mac 上装 x64 构建的 vsix 会静默失效 - 查
package.json最小支持版本：用unzip -p extension.vsix package.json | grep vscode提取字段，确保你本地code --version输出的主版本（如1.90.2→1.90）≥ 该值
为什么 code --install-extension 比拖放/图形界面更可靠
图形界面在内网、权限受限或路径含空格/中文时容易卡住、无提示、甚至假成功。而 CLI 是唯一走底层注册流程的入口：
- 错误信息直接输出到终端：
ENOENT表示路径错，EACCES是写入权限不足，EPERM多见于 Windows 杀软拦截 - Windows 下路径必须用英文双引号包裹，且推荐正斜杠：
code --install-extension "C:/ext/ms-python.python-2024.6.0.vsix" - 加
--force可覆盖同名旧版，但会清空用户配置（如 Python 解释器路径），慎用 - 若提示
command not found: code，先在 VSCode 里按Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH启用
手动解压复制到 extensions 目录为什么总不生效
这是最常踩的坑：把 .vsix 文件直接扔进 %USERPROFILE%\AppData\Roaming\Code\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.vsc。单装外壳，功能基本不可用。
- 真实依赖藏在
.vsix解压后的package.json的extensionDependencies字段里，别信插件页面写的 “Recommended” - 最稳方式：在已配好的联网机器上导出完整列表：
code --list-extensions > extensions.txt，再逐行用vsce download下载对应 vsix - 离线环境装完后，务必重启 VSCode 并检查
Developer: Show Running Extensions—— 若pylance显示为Uninstalled，说明它根本没被加载，不是“装了没反应”，是压根没进注册表
版本兼容性判断必须落在 package.json 的 engines.vscode 和本地 code --version 的主版本号比对上，其他任何经验性猜测都不可靠；依赖插件漏装时，VSCode 不会警告，只会让对应功能彻底消失——这点最容易被忽略。
