VSIX文件损坏会导致code --install-extension无响应、卡在“Installing…”或报corrupt及undefined错误；可用unzip -t校验完整性，仅官方Marketplace直链下载的带签名vsix才可靠。
vsix 文件损坏导致安装失败的典型现象
执行 code --install-extension 后无反应、卡在 “Installing…”、报 Extension is corrupt 或 Cannot read property 'engines' of undefined，这些基本不是网络问题，而是 .vsix 文件本身已损坏——VSCode 对 ZIP 结构和签名极其敏感，哪怕少一个字节或文件头被改写，就会静默拒绝加载。
用 unzip -t 快速验证 vsix 完整性
所有平台都可用系统原生命令校验，不依赖 VSCode：
- Linux/macOS：运行
unzip -t your-plugin.vsix，输出OK才算完整；若提示broken、missing或乱码，说明文件已损，必须重下 - Windows（PowerShell）：用
Expand-Archive your-plugin.vsix -WhatIf，不报错即结构可用；别用资源管理器右键“重命名”改后缀，那会破坏 ZIP 头 - 验证前先确认是原始
.vsix：用unzip -l plugin.vsix看顶层是否为extension/目录，且含extension/package.json；若显示一堆零散文件或报错，说明已被解压或转存异常
下载不完整最常被忽略的三个来源
很多人反复重下仍失败，是因为没避开这三类“伪官方”渠道：
- 浏览器插件生成的直链：常返回过期缓存或平台错配包（比如 M1 Mac 下了 x64 版）
- 第三方镜像站或网盘分享：缺失
.vsixmanifest和微软签名字段，VSCode 1.85+ 后默认拒载 - GitHub Release 页面的
cpptools-win32.vsix这类包：它只是核心插件，不含语言服务组件（如Microsoft.VSCode.CPP.Extension.linux），离线时功能残缺
真正能用的 vsix 必须走官方带签名的直链
唯一稳的方式是抓取 Marketplace 页面上 “Download Extension” 按钮触发的真实 URL，格式为：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/{publisher}/vsextensions/{extension_name}/{version}/vspackage
其中：
-
publisher和extension_name必须严格匹配插件 ID 小数点前后段（例如ms-python.python→ publisher=ms-python, extension_name=python） -
version必须与 Version History 里完全一致（如2026.6.123456），差一位数字都会导致engines.vscode校验失败 - 下载后建议重命名加入平台标识，例如
python-2026.6.123456-darwin-arm64.vsix，避免后续混用
最后提醒：即使文件校验通过，也得关掉所有 VSCode 进程再安装——后台残留的 Code Helper 会锁住 extensions 目录，导致覆盖失败或状态不一致。这不是玄学，是 VSCode 的进程模型决定的。
