用unzip -t your-extension.vsix校验，输出OK才完整；若报broken/missing则文件已损需重下，Windows禁用右键重命名，须用PowerShell复制生成新文件。
怎么用 unzip -t 快速验证 .vsix 是否损坏
.vsix 本质是 ZIP 包，结构损坏时 VSCode 会静默拒绝加载，报错如 Extension is corrupt 或 Cannot read property 'engines' of undefined。最直接的校验方式就是用系统自带的 unzip 工具做完整性扫描。
- Linux/macOS 终端执行：
unzip -t your-extension.vsix，输出OK才算完整；若提示broken、missing或任意 error，说明文件已损，重下是唯一解 - Windows 不要用右键“重命名”改后缀（比如
xxx.zip → xxx.vsix），这会破坏 ZIP 文件头。改用 PowerShell：Copy-Item "old.zip" "new.vsix" -Force复制生成新文件，再跑校验 - 别信文件大小：一个 4.2MB 的
.vsix可能内部缺失extension/package.json，而unzip -t会立刻暴露
为什么打开 .vsix 看不到 package.json 就不能装
VSCode 启动插件前必须读取 extension/package.json，它定义了插件名、版本、激活条件，最关键的是 "engines": { "vscode": "^1.85.0" } —— 没这个字段或路径不对，VSCode 直接判定为无效包，连版本比对环节都跳过。
- 用 7-Zip（Windows）或 Archive Utility（macOS）直接打开 .vsix，确认根目录下有
extension/文件夹，且里面包含package.json - 如果解压后只有
[Content_Types].xml或空目录，说明下载被截断，或源文件本身打包异常 - 某些非官方渠道的 .vsix 缺失
extension.vsixmanifest，虽不影响安装，但会导致--force也无法绕过部分校验，优先选 marketplace 直链
离线环境里，怎么提前知道 vsix 要求什么 VSCode 版本
市场页面写的 “Compatible with VS Code 1.80+” 是营销文案，真实兼容性只看 package.json 里的 engines.vscode 字段。离线时没法查文档，只能自己拆包读。
- Linux/macOS：用
unzip -p your-extension.vsix extension/package.json | grep engines提取关键行 - Windows：用 7-Zip 打开 .vsix → 进入
extension/→ 双击打开package.json→ 找"vscode":对应的值 - 常见陷阱：
"^1.85.0"表示 ≥1.85.0 且 =1.75.0" 才真正兼容 1.118.0；若你本地是1.84.2，而字段写"^1.85.0"，装了也白装
校验通过但安装仍失败？检查这三个隐藏前提
文件完整、版本匹配、路径正确——这三者全满足，才只是“能装”的起点。实际卡点常在更底层。
-
code --install-extension报ENOENT：不是路径错，是code命令根本没注册进 PATH。必须在 VSCode 里按Ctrl+Shift+P，搜并执行Shell Command: Install 'code' command in PATH - 拖拽到 VSCode 窗口没反应：确保当前打开了文件夹或文件（即已加载工作区），纯空白启动页不响应拖放；目标区域必须是编辑器主区域，不是侧边栏或设置页
- 装完
code --list-extensions能看见，但插件不生效：运行Developer: Show Running Extensions查状态，很多插件（如ms-python.python）依赖ms-python.pylance，缺一个就停在 “Activating…”
真正容易被忽略的是：**.vsix 里声明的 engines.vscode 版本，和你本地 code --version 输出的版本号，必须满足语义化版本规则，而不是简单比较数字大小**。比如 "^1.85.0" 和 1.118.0 看似兼容，实则不匹配——因为 ^ 只允许补丁和次要版本升级，跨主版本（1.85 → 1.118）会被拒绝。
