直接解压.vsix（即ZIP包），检查extension/package.json是否存在、能否被JSON解析器读取；路径错位、字段缺失、语法错误（如含注释）、engines.vsicode格式非法或版本不兼容，均会导致“extension/package.json not found inside zip”错误。
如何快速验证.vsix里的package.json是否合法
直接解压.vsix文件（它就是个ZIP包），检查extension/package.json是否存在、能否被JSON解析器读取。VSCode安装时会严格校验这个文件：路径错位（比如放在根目录而非extension/下）、字段缺失或语法错误，都会报extension/package.json not found inside zip。
常见错误包括：
-
package.json被误放到了package.json根层，而不是extension/package.json - 用了注释（JSON标准不支持
//或/* */），导致解析失败 -
engines.vscode值为空、格式非法（如"^1.8"缺小版本号）或版本范围过窄（如"1.85.0"写死，无法兼容1.85.1）
package.json中哪些字段影响离线安装成败
离线安装不走 Marketplace 校验，但 VSCode 仍会强制检查几个关键字段：
-
publisher和name组合必须构成唯一标识，且不能含空格或非法字符；否则code --install-extension可能静默跳过或报Extension not found -
version必须符合语义化版本规范（X.Y.Z），带字母、横线或前导零（如"1.02.0"）会导致安装失败 -
engines.vscode决定最低兼容版本；若当前 VSCode 版本低于该范围（如"^1.84.0"而你用的是1.83.2），插件不会加载，也不报错——只在扩展面板里显示“已禁用” -
extensionDependencies列出的依赖项若未提前安装，插件可能激活失败，但控制台通常只报Cannot activate extension，不提示缺哪个依赖
修改package.json后怎么重新打包成可用.vsix
改完package.json不能直接压缩成.zip再改后缀——VSCode 对 ZIP 内部结构有硬性要求，必须用vsce package生成。
执行前确保：
- 已全局安装
vsce：npm install -g @vscode/vsce - 当前目录是含
package.json的扩展根目录（不是extension/子目录） - 删掉
vsc-extension-quickstart.md等模板残留文件（它们会干扰vsce读取） - 运行
vsce package，生成的文件名自动为{publisher}.{name}-{version}.vsix，命名必须与package.json里三字段完全一致
如果想适配旧版 VSCode，可手动改engines.vscode后再打包，但别改version字段——否则新包名与package.json不匹配，安装时会被拒绝。
为什么拖拽安装成功但插件不工作
拖进 VSCode 成功只说明 ZIP 结构和签名通过了初步校验，不代表功能就正常。尤其要注意：
- 含原生模块的插件（如
ms-vscode.cpptools）若.vsix没指定targetPlatform，可能装上了却找不到./dist/extension入口文件 -
activationEvents配置不当会导致插件“已启用”但永不激活，比如设了"onCommand:xxx"却没注册对应命令 - 开发时本地改过
main字段指向的路径（如从./out/extension.js改成./src/extension.ts），但没编译就打包，运行时直接报Cannot find module
这类问题往往没有明显报错，只能打开开发者工具（Ctrl+Shift+I）看 Console 里有没有require失败或activate抛异常。
