离线安装VSCode插件失败的主因是版本、.vsix结构或安装路径未对齐；需确认VSCode就绪状态、检查策略限制、验证engines.vscode兼容性、手动补全语言服务器依赖，并严格按规范解压复制到对应extensions目录。
离线环境下装不上插件，大概率不是操作错，而是 vscode 版本、.vsix 结构或安装路径这三个环节中有一个没对齐。别急着重试，先盯住这三点。
拖拽安装没反应？先确认 VSCode 是否“真就绪”
很多人以为只要 VSCode 启动了就能拖，其实它得同时满足：有系统焦点、未全屏、没连远程桌面、且拖的是未解压的 .vsix 文件。
- 任务栏图标没高亮？点一下编辑器空白处再拖
- 用 RDP 或 TeamViewer 连内网机器？退出全屏，或改用命令行
- 浏览器下载后自动把
xxx.vsix改成xxx.vsix.zip？别右键重命名，用 PowerShell 执行：Copy-Item "xxx.vsix.zip" "xxx.vsix" -Force - 拖进去后右下角弹出 “Extensions disabled by policy”？说明企业策略禁用了扩展，得走手动解压方案
code --install-extension 报错 ENOENT 或 not compatible？查路径和版本
ENOENT 不是路径写错了，是 code 命令根本没注册进系统 PATH；not compatible with Code 则几乎全是 engines.vscode 版本不匹配导致的静默拒绝。
- 先运行
code --version，取结果里第一个小数点前的两位（如1.85.2→1.85） - 用
unzip -p your.vsix extension/package.json | grep engines（Linux/macOS）或 7-Zip 打开查看"vscode": "^1.80.0"—— 你本地版本必须 ≥ 这个值 - Windows 下路径含空格或中文？必须加英文双引号：
code --install-extension "C:\my ext\python.vsix" - 提示
command not found: code？在 VSCode 里按Ctrl+Shift+P，输入Shell Command: Install 'code' command in PATH并执行
插件装了但 Python/Prettier 不工作？语言服务器依赖没带进来
很多插件（如 ms-python.python、esbenp.prettier-vscode）首次启用时会自动下载二进制依赖（pyright、prettier CLI），离线环境卡在 “Downloading…” 就是这个原因。
- 别只拷
.vsix，要提前在有网机器上完整跑一遍：打开 .py 文件 → 触发下载 → 等状态栏不显示 “Downloading” → 再去%USERPROFILE%\.vscode\extensions\（Windows）或$HOME/.vscode/extensions/（macOS/Linux）里整个拷对应文件夹（如ms-python.python-2024.6.0/） - 手动复制后，必须彻底退出 VSCode（包括右下角托盘进程），否则缓存不刷新
- 验证是否生效：打开命令面板（
Ctrl+Shift+P），输入Python: Select Interpreter或Prettier: Format Document，能调出来才算真装好
手动解压 + 复制到 extensions 目录的硬核姿势
当图形界面被锁、CLI 不可用、或部署到无 GUI 的服务器时，这是唯一兜底方式。但它要求目录结构完全对齐，错一个字符都识别不到。
- 先解压：
unzip your.vsix -d unpacked/，然后看顶层目录名，比如esbenp.prettier-vscode-9.10.3/—— 这就是扩展 ID + 版本，不能删、不能改 - 目标路径必须是用户级 extensions 目录：
– Windows：%USERPROFILE%\AppData\Roaming\Code\Extensions\
– macOS：$HOME/Library/Application Support/Code/Extensions/
– Linux：$HOME/.vscode/extensions/ - 把整个
esbenp.prettier-vscode-9.10.3/文件夹复制进去，不是里面的内容，也不是.vsix文件本身 - 重启 VSCode 后，在命令面板运行
Developer: Show Running Extensions，状态应为Local，不是Marketplace
最易被忽略的是：插件列表里显示“已安装”，不代表它能响应文件类型或执行命令。真正有效的验证永远落在具体动作上——选中代码按 Ctrl+Shift+P 调出插件专属命令，或者打开对应后缀文件看状态栏有没有加载指示。版本兼容性不报错，只沉默跳过；依赖缺失不提示，只卡在“Downloading…”；这些静默行为才是离线部署里最耗时间的坑。
