VSCode离线安装插件成功的关键是正确使用.vsix文件、匹配版本并确保路径准确；拖拽无效多因焦点/环境问题，命令行需绝对路径和CLI注册，手动复制须严格保持目录结构，兼容性与依赖缺失是装后不生效的主因。
VSCode离线安装插件，只要用对.vsix文件、走对路径、版本对得上，就能一次成功——不是玄学，是 VS Code 官方明确支持的标准流程。
拖拽.vsix到主窗口没反应？先看这三件事
这是离线安装里最常被误判为“失败”的场景，实际几乎全是环境干扰：
- VSCode 没获得系统焦点：点击编辑器任意空白处，确认任务栏图标高亮后再拖
- 当前处于全屏、远程桌面（如 RDP/TeamViewer）或 macOS 的多显示器缩放偏移状态：这些环境会拦截拖放事件，退出全屏或改用命令行
- 拖的是解压后的文件夹、重命名的.zip、或 GitHub clone 下来的源码目录：
VSCode 只认原始未解压的 .vsix 文件；可用unzip -l xxx.vsix看顶层是否为extension/目录
拖入后弹出确认框即表示识别成功；安装完插件默认禁用，需手动点「启用」图标或重启 VSCode。
code --install-extension 命令总报错？路径和 CLI 是关键
该命令不走网络，只读取本地文件并写入扩展目录，但容错极低，报错即说明路径或环境有硬伤：
- 必须用绝对路径：
code --install-extension /home/user/ext/prettier-9.10.3.vsix（Linux/macOS），code --install-extension C:/ext/ms-python.python-2024.6.0.vsix（Windows，推荐正斜杠） - 路径含空格或中文？必须加英文双引号：
code --install-extension "/path/to/my ext.vsix" - 提示
command not found: code？说明 CLI 未注册：在 VSCode 中按Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH并执行 - 静默覆盖旧版可加
--force参数：code --install-extension prettier.vsix --force
手动复制到 extensions 目录？结构错一丁点就白忙
适用于无 GUI、权限受限或 CLI 不可用的服务器环境，但步骤严格，容错率为零：
- 先用
unzip -l xxx.vsix查顶层目录名，例如esbenp.prettier-vscode-9.10.3/—— 这就是扩展 ID + 版本号，必须原样作为子目录名 - 解压后把整个该目录（含
package.json、node_modules等）复制进对应路径：
Windows：%USERPROFILE%\AppData\Roaming\Code\Extensions\
macOS/Linux：$HOME/.vscode/extensions/ - 不能只复制里面的内容，也不能保留
.vsix文件本身，更不能丢掉外层目录 - 复制完必须彻底退出 VSCode（包括右下角托盘进程），否则缓存不刷新，日志里会出现
Extension 'xxx' is not installed
装完不显示、没功能？别急着重装，先查兼容性
VSCode 对版本不兼容的处理非常安静：不报错、不提示、只是跳过加载。排查要直击根源：
- 打开
.vsix解压后的package.json，找"engines": {"vscode": "^1.80.0"} - 运行
code --version，取输出中第一位小数点前的数字（如1.85.2→1.85），需 ≥ 插件要求的最低版本 - ARM Mac 上装 x64 构建的插件（尤其含 native binary 的）会静默失败，得找带
darwin-arm64的 vsix - 依赖缺失也会导致功能异常：比如
ms-python.python依赖ms-python.vscode-pylance，两个.vsix都得装，且首次启用时可能卡在 “Downloading…”（离线环境下 LSP 服务无法拉取）
版本和依赖这两项，是离线安装中最容易被跳过、却最决定成败的环节。
