VS Code离线安装失败主因是未真正断网或.vsix包校验失败；需用命令行校验压缩包完整性、确认package.json存在且vscode版本兼容、确保code命令已加入PATH、路径使用正确格式，并在Remote环境下单独部署语言服务器等依赖组件。
离线安装失败，90% 是因为 VS Code 没真正“断网”或 .vsix 文件没过校验关——图形界面拖拽、双击、菜单选文件都会触发后台联网请求，失败后才 fallback 到本地包，但此时签名/结构错误已暴露无遗。
code --install-extension 命令报 “Extension is not a valid VS Code extension”
这不是路径写错了，而是 .vsix 包本身被破坏或格式不合规。VS Code 对压缩包完整性极其敏感：少一个 extension/package.json、多一个空格、甚至 ZIP 中文件时间戳异常，都会直接拒载。
- 用
unzip -t your-extension.vsix校验压缩包（Linux/macOS）；Windows 用 PowerShell 执行Test-Archive -Path "your-extension.vsix"（需 PowerShell 7+），别用资源管理器右键解压再重命名 - 打开
.vsix（本质是 ZIP），确认根目录下有extension/package.json，且其中"engines": { "vscode": "^1.80.0" }的版本号 ≤ 你本地 VS Code 版本（code --version查） - 如果文件是从浏览器下载的，检查是否被杀软或 Edge/Chrome 自动重命名为
xxx.vsix.zip或xxx.vsix.part——这类文件 VS Code 一律不认
安装时提示 “ENOENT” 或 “command not found”
不是 .vsix 路径错，而是 code 命令根本没注册进系统 PATH。VS Code 图形界面启动时自带环境变量，但终端默认不继承。
- 先在 VS Code 里按
Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH并执行 - 关闭所有 VS Code 进程（包括后台的
Code Helper），再新开终端测试code --version - Windows 路径含空格必须加英文双引号：
code --install-extension "C:\Users\Alice\Downloads\ms-python.python-2024.6.0.vsix" - Linux/macOS 必须用绝对路径，不能用
~/或相对路径：code --install-extension /home/alice/Downloads/redhat.java-1.42.0.vsix
插件装上了但不生效，控制台报 “Extension activation failed”
常见于 Java、Python 等语言类插件——它们依赖外部二进制服务（如 java-language-server、pyright），而离线环境下这些依赖根本没部署。
- Java Pack 必须按顺序装：
redhat.java→vscjava.vscode-java-debug→ms-vscode.vscode-java-pack，漏一个就激活失败 - Python 插件离线运行需提前下载对应平台的
python-language-server或pylsp二进制包，并配置"python.defaultInterpreterPath"指向本地路径 - 打开开发者工具（
Help → Toggle Developer Tools），切到 Console 标签页，找Cannot find module或spawn ENOENT，那通常就是缺某个 CLI 工具或二进制文件 - 某些插件（如 ESLint）要求全局安装 CLI：
npm install -g eslint，仅装插件无效
企业内网或 Remote SSH 下离线安装仍失败
Remote 环境下，VS Code 会尝试在远程机器上联网拉取语言服务器、依赖包甚至 node_modules，和本地安装逻辑完全不同。
- Remote SSH 连接后，先在远程终端运行
curl -I https://marketplace.visualstudio.com，确认网络通不通——不通就别试在线安装 - 不要指望本地代理自动转发，必须在远程 shell 配置（如
~/.bashrc）里显式设置HTTP_PROXY和HTTPS_PROXY - 传
.vsix到远程后，别用图形界面点“Install from VSIX”，改用远程终端执行：code --install-extension /tmp/ms-python.python-2024.6.0.vsix - 若远程缺构建工具（
gcc、python3、make），部分插件会静默崩溃；查日志：tail -f ~/.vscode-server/data/logs/*/exthost*/window*
最麻烦的从来不是“装不上”，而是“装上了却不动”——比如 Python 插件显示已启用，但没有语法检查、没有调试按钮，问题往往出在语言服务器没启动，而不是插件本身。离线场景下，得把每个依赖环节都当成独立组件来验证，不能只盯着 .vsix 文件。
