必须用Open VSX协议，因VSCode官方市场不支持私有化部署，而Open VSX是Eclipse基金会维护的开放标准，自1.63版起被VSCode原生支持；其他自建HTTP服务返回JSON会被静默忽略。
私有扩展源为什么必须用 Open VSX 协议
VSCode 官方市场（marketplace.visualstudio.com）不支持私有化部署，所有扩展分发都走微软控制的中心化服务。想绕过它，唯一被官方兼容的替代方案是 Open VSX 协议——它是 Eclipse 基金会维护的开放标准，VSCode 从 1.63 版本起原生支持通过 extensionsGallery 配置切换市场源。不走这个协议，客户端根本不会向你的服务器发请求；用自建 HTTP 服务返回 JSON 列表也无效，VSCode 会静默忽略。
jvs-server 是最轻量的私有源启动方式
中小团队直接上 jvs-server 最省事：它不依赖数据库、无管理后台、纯内存缓存，启动即用。常见错误是没改端口或没配反向代理：
- 默认监听
http://localhost:5000，生产环境必须用 Nginx 反代到 HTTPS 域名（如https://vsx.your-company.com），否则 VSCode 拒绝加载非安全源 - 启动前确认 Node.js 版本 ≥ 16，执行
npm run start后访问/vscode/gallery应返回空数组[]，不是 404 或 HTML 页面 - 上传扩展必须用
ovsxCLI（不是 vsce），命令形如：ovsx publish your-extension-1.0.0.vsix --registry https://vsx.your-company.com
VSCode 客户端配置必须写进 settings.json
不能靠 UI 设置，必须手动编辑全局或工作区 settings.json。漏掉任一字段或 URL 格式错，VSCode 就退回官方市场：
-
serviceUrl必须以/vscode/gallery结尾，且协议、域名、路径全部小写 -
itemUrl和resourceUrlTemplate中的{publisher}、{name}等占位符不能删、不能改顺序 - 改完保存后必须重启 VSCode（不是重载窗口），否则设置不生效；检查左下角是否显示 “Extensions: Private Gallery” 提示
扩展发布前要确保 .vsix 文件合法
本地打包的 .vsix 若含非法字段或签名缺失，jvs-server 会接收但 VSCode 安装时报 Extension is not valid：
- 用
vsce package打包时，package.json中的publisher字段不能含下划线或大写字母（只允许小写字母、数字、短横线） -
engines.vscode版本范围需覆盖团队最低 VSCode 版本，例如"^1.63.0"，写成=1.80.0"会导致旧版本无法安装 - 上传后访问
https://vsx.your-company.com/vscode/item/{publisher}/{name}能看到元数据，但点击 Install 仍失败？大概率是.vsix内extension/package.json的id字段与实际 publisher/name 不一致
私有源真正卡住人的地方，往往不在部署服务，而在 VSCode 客户端那一行 serviceUrl 的拼写——少一个斜杠、多一个空格、协议写成 http 而非 https，都会让整个流程静默退回到官方市场。
