离线安装.vsix失败主因是VSCode未识别插件、版本不兼容或权限不足；需查Extension Management日志确认是否触发安装，exthost.log检查是否激活及版本匹配，再用unzip和code --version比对engines字段。
离线安装 .vsix 失败，90% 不是插件坏了，而是 VSCode 没真正“看到”或“接受”它——必须查日志、验版本、看权限，三者缺一不可。
怎么看安装到底卡在哪一步？
VSCode 界面不报错，也不提示失败点，所有线索都在日志里。关键不是“打开日志”，而是分清两套日志系统：
-
Extension Management日志：记录“是否开始处理这个.vsix”。按Ctrl+Shift+P→ 输入并执行Developer: Open Extension Logs，打开后搜你刚拖入的文件名（如python.vsix）。如果完全没出现，说明 VSCode 根本没收到拖放事件——大概率是窗口没焦点、全屏、或远程桌面拦截了。 -
exthost.log日志：记录“插件有没有活过来”。执行Developer: Open Logs Folder→ 进入exthost子目录 → 打开最新日志 → 搜activate+ 插件 ID（如ms-python.python）。如果搜不到，或出现Skipping extension ... no matching engine，说明版本不兼容，被静默跳过。
为什么报 “Extension is not compatible with Code” 却没提示？
这不是警告，是拒绝动作。VSCode 会直接跳过加载，连错误堆栈都不打出来。根本原因是 .vsix 包内 package.json 的 "engines": {"vscode": "^1.85.0"} 和你本地 code --version 输出不匹配。
- 用
unzip -p your.vsix package.json | grep engines（Linux/macOS）或 7-Zip 解压后打开package.json查声明版本 - 运行
code --version取前两位（如1.91.0→1.91），必须 ≥ 插件要求的最低版本（^1.85.0表示 ≥ 1.85.0 且 - 别改
package.json再重打包：签名失效后插件可能被禁用，或首次激活时报Cannot read property 'engines' of null
装上了但功能不出现？LSP 和 native 二进制根本没落地
很多插件（如 ms-python.python、volarjs.volar、esbenp.prettier-vscode）只靠 .vsix 安装，只是注册前端界面；语言服务器（pyright-server、volar-server）、CLI 工具（prettier CLI）或调试器后端（cpptools-srv、lldb）需首次启用时联网下载——离线环境必然卡在 Downloading...。
- 正确做法：在有网机器上完整触发一次——打开一个
.py文件，等状态栏显示Python interpreter selected或Ready，再关掉 VSCode - 把整个
~/.vscode/extensions/ms-python.python-2024.6.0/目录（含子目录里的node_modules、dist、out和 native 二进制）拷到离线机对应路径下 - 复制完必须彻底退出 VSCode（包括右下角托盘进程），否则缓存不刷新，新文件不生效
权限和路径问题怎么快速验证？
即使 .vsix 合法、版本对得上，仍可能因磁盘写入失败而中断。这类错误不出现在扩展日志里，而在 main.log 中：
- 执行
Developer: Open Logs Folder→ 打开最新日期文件夹下的main.log→ 搜ENOENT（父目录不存在，比如extensions文件夹被删）或EACCES（权限拒绝，常见于 WSL、云桌面或杀软拦截） - 命令行安装时，路径必须是绝对路径：
code --install-extension /home/user/ext/python.vsix（Linux/macOS），Windows 推荐正斜杠：code --install-extension C:/ext/ms-python.python-2024.6.0.vsix - 路径含空格或中文？必须加英文双引号：
code --install-extension "/path/to/my ext.vsix" - 报
command not found: code？不是 PATH 问题，是 VSCode 没启用 Shell 命令：按Ctrl+Shift+P→ 输入Shell Command: Install 'code' command in PATH→ 回车
