离线安装失败主因是code命令未注册、VSCode与插件版本不兼容、扩展目录权限错误；需用which code验证PATH，通过Shell Command注册CLI，检查engines.vscode版本匹配，并避免sudo安装导致路径错位。
离线安装失败，90%不是插件本身的问题，而是环境没配对——code 命令不可用、VSCode 版本和 .vsix 不兼容、扩展目录权限不对，这三处卡住，安装就直接静默失败或报错“command not found”。
code 命令找不到？先确认它是否在 PATH 里
离线环境下，code --install-extension 是最常用安装方式，但它依赖系统能识别 code 这个命令。Ubuntu/Debian 的官方 .deb 包默认不把 /usr/bin/code 加入 PATH，尤其在 SSH 登录、非交互式终端中更常见。
- 运行
which code：无输出即说明命令不可见 - 临时解决：用绝对路径，例如
/usr/bin/code --install-extension /path/to/plugin.vsix - 永久解决：把
/usr/bin加入$PATH（修改~/.bashrc或/etc/environment），再执行source ~/.bashrc - 切记不要加
sudo执行code --install-extension，否则插件会装到/root/.vscode/extensions/，普通用户启动 VSCode 后根本看不到
vsix 安装后不生效？检查 engines.vscode 版本兼容性
VSCode 插件的 package.json 里必须声明支持的最低客户端版本，比如 "engines": {"vscode": "^1.85.0"}。如果你本地是 1.79.2，VSCode 就会拒绝安装——而且不报错、不提示，只是静默跳过。
- 用
unzip -p plugin.vsix package.json | grep engines提取插件要求的 VSCode 版本 - 运行
code --version确认本地版本 - 不匹配时，要么升级 VSCode（需离线安装新版
.deb），要么去 Marketplace 的/versionhistory页面手动下载旧版.vsix - 强行修改
package.json并重打包虽可行，但会绕过签名验证，插件可能被禁用或关键功能异常，生产环境不建议
拖放 .vsix 文件没反应？GUI 权限和挂载点限制是主因
在 VMware/VirtualBox 虚拟机中，从 Windows 共享文件夹（如 /mnt/hgfs）直接拖 .vsix 到 VSCode 窗口，经常卡住或无响应。这不是 VSCode bug，而是 GUI 应用读取 FUSE 挂载点时受属主和权限限制。
- 安全做法：先把
.vsix复制到本地路径，例如~/Downloads/，再拖放或通过「… → Install from VSIX」选择 - 检查挂载选项：
mount | grep hgfs，确认含uid=1000,gid=1000（对应当前用户），否则文件属主为root，VSCode 无权读取 - 若用
code --install-extension命令行安装，路径必须是本地可访问路径，不能是挂载点下的符号链接或远程路径
最容易被忽略的是：离线安装成功后，插件仍不激活——往往是因为语言服务没起来、路径别名没配置、或自动导入开关关着。这些不是安装问题，而是运行时依赖，得进项目里单独调。
