VSCode报“package.json not found inside zip”主因是vsix结构错误：extension/package.json缺失或路径不正确，而非文件真损坏；需验证ZIP完整性、检查路径、确保engines.vscode版本匹配。
VSCode 报 “Extension is corrupt” 或 “package.json not found inside zip”，基本不是文件真坏了，而是校验直接被拒——它压根没开始解压，就卡在签名、结构或版本检查环节。
vsix 文件本质是 ZIP，先用 unzip -t 验证完整性
很多所谓“损坏”其实是下载中断导致的 ZIP 结构断裂。VSCode 不会告诉你这点，只报模糊错误。
- Linux/macOS：运行
unzip -t your-extension.vsix，输出OK才算完整；若提示broken或missing，必须重下，--force也救不回来 - Windows PowerShell：用
Expand-Archive your-extension.vsix -WhatIf，不报错才说明 ZIP 可解压 - 别信文件大小：一个 2KB 的 vsix 很可能只是 HTTP 404 响应体被保存成了 .vsix
extension/package.json 缺失或路径错位是高频硬伤
VSCode 要求 package.json 必须严格位于 extension/ 子目录下。手动改包、非官方打包工具或 macOS 自动写入的 ._* 隐藏文件都可能破坏该结构。
- 把
.vsix改成.zip后解压，确认是否存在extension/package.json—— 若只有根目录下的package.json，就属于路径错误 - 清理 macOS 元数据：
zip -d your-extension.vsix '._*' - 修复结构后，用官方工具重打：
vsce package（需先npm install -g vsce，且当前目录含合法package.json）
engines.vscode 版本不匹配，--force 也无效
--force 能跳过签名和版本比对，但前提是 VSCode 能走到安装逻辑。如果 package.json 里声明了 "engines": {"vscode": "^1.95.0"}，而你本地是 1.94.2，VSCode 连解压都不会触发，直接报错。
- 查本地版本：
code --version - 查 vsix 要求：解压后打开
extension/package.json，看engines.vscode字段 - 不匹配时，
--force完全无效 —— 只能升级 VSCode，或找旧版 vsix（插件页点 ⋯ → Install Another Version…）
code --install-extension 失效？先杀干净后台进程再试
code --install-extension xxx.vsix --force 看似万能，但 VSCode 主进程若已加载同名扩展，命令会被静默忽略，连错误都不抛。
- Windows：任务管理器中结束所有
Code.exe和Code Helper.exe - macOS/Linux：终端执行
killall -u $(whoami) code或用活动监视器清空全部 Code 相关进程 - 权限问题：若
~/.vscode/extensions/被锁为只读（常见于企业策略或 SIP），需先sudo chown -R $(whoami) ~/.vscode
真正难搞的从来不是 ZIP 解压失败，而是 VSCode 在你没看见的地方做了四层校验：ZIP 结构 → extension/package.json 路径 → engines.vscode 版本 → 签名有效性。每一步断掉，表现都是“损坏”，但修复动作完全不同。
