.vsix 文件需经 vscode 主进程解压、校验、注册才生效；离线安装失败主因是版本不匹配、路径错误或静默跳过加载，而非网络问题。
.vsix 文件不是“放进去就生效”的静态资源，它必须经 VSCode 主进程解压、校验、注册后才真正可用。离线安装失败，90% 不是网络问题，而是版本不匹配、路径误操作或静默跳过加载。
VSCode 版本和 .vsix 兼容性怎么查？
VSCode 不会主动报错说“你版本太低”，而是静默忽略插件——尤其用拖拽或图形界面安装时，连提示都没有。
- 运行
code --version，取输出第一行的主版本号（如1.90.2→ 看作1.90） - 用
unzip -p your-extension.vsix extension/package.json | grep engines（Linux/macOS）或 7-Zip 打开.vsix查package.json中的"engines": {"vscode": "^1.85.0"} - 要求：本地 VSCode 主版本号 ≥ 插件声明的最低版本；架构一致（
arm64机器不能装x64编译的含 native 二进制的插件，如esbuild相关）
code --install-extension 命令为什么比拖拽更可靠？
拖拽看似简单，但在企业锁屏、远程桌面、全屏状态或策略禁用下极易失效；而命令行能立刻暴露真实问题。
- 必须用绝对路径：
code --install-extension /home/user/ext/prettier-9.10.3.vsix（Linux/macOS），Windows 推荐正斜杠：code --install-extension C:/ext/python-2024.6.0.vsix - 路径含空格或中文？加英文双引号：
code --install-extension "/mnt/USB/My Ext.vsix" - 静默覆盖旧版：
code --install-extension xxx.vsix --force - 验证是否成功：
code --list-extensions | grep ms-python
拖进主窗口没反应？先确认这三件事
这不是 bug，是条件未满足。VSCode 对拖放行为非常挑剔。
- VSCode 是否获得系统焦点？任务栏图标未高亮 = 没焦点，点一下编辑区再试
- 是否处于全屏模式或 RDP/TeamViewer 远程会话？这类环境常拦截拖放事件，退出全屏或改用命令行
- 拖的是不是原始
.vsix文件？解压过的文件夹、.zip、或重命名过的文件都不认——unzip -l xxx.vsix应看到顶层是extension/目录
手动复制到 extensions 目录为什么常失败？
直接把 .vsix 文件扔进 ~/.vscode/extensions/ 是无效的。VSCode 启动时只扫描已解压的子目录，且目录名必须严格匹配扩展 ID + 版本。
- 先解压：
unzip -o your-extension.vsix -d /tmp/ext - 看顶层目录名：
ls /tmp/ext→ 得到类似ms-python.python-2024.6.0/的文件夹 - 完整复制该文件夹（不是里面的内容）到
~/.vscode/extensions/ - 彻底退出 VSCode（包括右下角托盘进程），再重启 —— 缓存不清理，新目录会被跳过
engines.vscode 和 code --version，能省掉两小时排查。
