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；若显示一堆零散文件或报错，说明已被解压或转存异常

下载不完整最常被忽略的三个来源

很多人反复重下仍失败，是因为没避开这三类“伪官方”渠道：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 浏览器插件生成的直链：常返回过期缓存或平台错配包（比如 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 的进程模型决定的。