VSCodium扩展市场Failed to fetch：根因排查与镜像换源全解

如果你用的是微软原版 VS Code，扩展市场几乎没人会去折腾。但换成 VSCodium、自建 code-server，或者任何围绕 VS Code 内核做的 Web IDE 后，打开扩展面板出现这类日志就成了家常便饭：

[error] [网络] #1824: https://open-vsx.org/vscode/gallery/extensionquery-error POST Failed to fetch

我第一次遇到时，第一反应是网络卡了，点了三次重试，接着把 VSCodium 整个删掉重装，结果扩展列表还是空的。后来才搞清楚，这个报错根本不是某个扩展的问题，而是编辑器在向扩展市场服务 open-vsx.org 发起查询时，请求根本没有得到响应。这篇文章从“这条链路到底断在哪”开始讲，把排查命令、镜像换源、product.json 修改、离线安装兜底这些方案一步步拆开，VSCodium 用户、code-server 维护者，以及需要帮团队封装开发镜像的工程同学都可以直接照着做。

1. 错误全貌与根因分析

1.1 这个错误到底发生在哪个环节

先解决一个最容易混淆的点：日志里的#1824不是 HTTP 状态码，也不是 open-vsx 那边的错误编号。我在不同机器上见过这个数字变化，它更像编辑器日志模块给事件累加的一个序号。排障时盯着它没有意义，关键是看后面两段文字：URL 和POST Failed to fetch。

打开扩展面板时，VS Code 系产品会按配置里的extensionsGallery.serviceUrl拼出一个查询地址。对 VSCodium 这类默认走 open-vsx 的发行版来说，这个地址就是https://open-vsx.org/vscode/gallery/extensionquery。客户端把搜索词、过滤条件、分页信息封装成 JSON，用 POST 方式发过去，服务端返回扩展列表。open-vsx 兼容了 VS Code 这套接口，所以这些编辑器不需要微软官方市场的访问凭证，也能正常搜索和安装扩展。

问题就出在这个 POST 请求上。Failed to fetch是浏览器和 Electron 内置 fetch API 在网络请求没完成时抛出的 TypeError。它不是“服务端返回了一个 500 错误页”，而是“请求根本没有等到响应”。用生活里的例子说，就是你去商店问店员有没有货，结果还没走到门口就被拦在路上了，店员到底有没有货你完全不知道。这个区别很重要，因为服务端错误通常等一会儿重试就好，而请求中断的问题往往需要从网络链路上找原因。

我把这条链路拆得再细一点，顺便解释为什么不能靠“多试几次”解决。

1.2 为什么 fetch 会失败：一次网络请求的完整拆解

一个 HTTPS POST 请求，从按下发送到拿到响应，中间要过四道关卡。

第一关是域名解析。请求要先知道 open-vsx.org 的 IP 是多少。操作系统会查 hosts 文件、本地 DNS 缓存，然后向 DNS 服务器发起递归查询。如果 hosts 里写了一个不能用的旧 IP，或者本地 DNS 返回了异常结果，请求在这里就会直接失败。这类失败日志里常伴随ERR_NAME_NOT_RESOLVED或者ENOTFOUND。

第二关是 TCP 建连。拿到 IP 后，客户端要和目标主机的 443 端口建立 TCP 连接。如果网络链路不畅通、目标 IP 被安全网关丢弃、或者中间设备大量丢包，三次握手会一直重试到超时。对应日志一般是ERR_CONNECTION_TIMED_OUT或ERR_CONNECTION_REFUSED。

第三关是 TLS 握手。连接建立后，双方交换证书，验证身份。如果 open-vsx 的证书链不被本机信任、企业内网插入了自定义证书、或者系统时间偏差很大，握手就会失败。日志关键词通常是ERR_CERT_AUTHORITY_INVALID、ERR_CERT_DATE_INVALID。

第四关才是真正发送 HTTP 请求体并等待响应。就算前三关都过了，请求发出后也可能被中间的安全设备以各种理由掐断，表现为请求发出去后迟迟没有返回，最终汇总成一句Failed to fetch。

这么一拆就明白了：标题里那一行报错只告诉你“POST 没拿到结果”，但没说断在第几关。所以排查顺序应该从上往下逐层验证，不能一上来就改配置。我习惯用下面这个对应关系快速判断范围。

阶段	常见日志关键词	优先怀疑方向
DNS 解析	ERR_NAME_NOT_RESOLVED / ENOTFOUND	hosts 误写、DNS 配置异常
TCP 建连	ERR_CONNECTION_TIMED_OUT / REFUSED	访问链路受限、服务端端口不可达
TLS 握手	ERR_CERT_AUTHORITY_INVALID / DATE_INVALID	证书链不完整、系统时间错误
HTTP 传输	Failed to fetch / net::ERR_EMPTY_RESPONSE	请求被中途掐断、服务端响应异常

2. 动手排查：三分钟定位卡点

2.1 先确认 open-vsx 服务本身是否可用

排查的第一步不是改任何配置，而是先确定到底是只有你的网络到不了 open-vsx，还是服务端本身出了问题。方法很简单，用 curl 探一下。

curl -sS -I --max-time 10 https://open-vsx.org

如果返回HTTP/2 200，说明域名能解析、端口能连通、证书也有效，问题大概率出在客户端这一侧。如果命令卡住不返回，直到超时，那就是链路有问题。

但是-I只验证了 GET 请求，扩展面板实际发的是 POST，所以最好把请求条件完整打一遍：

curl -sS --max-time 15 \ -X POST "https://open-vsx.org/vscode/gallery/extensionquery" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "User-Agent: vscode/1.80.0" \ -d '{"filters":[{"criteria":[{"filterType":7,"value":"vscodevim.vim"}]}]}'

返回的 JSON 里如果totalSize大于 0，说明 open-vsx 接口本身工作正常。如果返回的是502或503，说明服务端或它依赖的后端正在报错，这时候只能等服务恢复，或者直接换镜像。

有个细节值得多说一句：命令行 curl 走的是系统网络栈，Electron 应用有时不完全一样，比如证书信任库、底层网络参数的加载方式都可能有差异。所以 curl 通了只能排除服务端挂掉，不能百分百保证编辑器一定通。反过来，curl 都不通，编辑器也几乎不可能通，这时候就可以安心查网络了。

2.2 本地 DNS 与 hosts 检查

确认服务端正常后，下一步看 DNS。很多人会跳过这一步直接改配置，但如果是 hosts 文件里残存了一个旧 IP，不管你怎么换镜像都会被劫持到错误地址。

先检查系统 hosts：

• Windows：C:\Windows\System32\drivers\etc\hosts
• Linux/macOS：/etc/hosts

用编辑器打开，搜open-vsx.org。如果里面有这个域名的映射，但又不是你刚通过 DNS 查到的有效 IP，建议先删掉。我见过某台机器 hosts 里写着一条两年前手加的 open-vsx 记录一直没删，后来官方换了 IP，扩展市场就彻底打不开了，看起来像是“官方挂了”，实际是本地把域名指到了老地址。

然后用nslookup看当前解析结果：

nslookup open-vsx.org dig +short open-vsx.org @223.5.5.5

223.5.5.5是一个常用的公共 DNS，用来和系统解析结果做对比。如果系统解析出来的 IP 和公共 DNS 返回的差异很大，或者系统解析超时，可以考虑临时把系统 DNS 切到公共 DNS 再试。

注意换完 DNS 之后要清一下缓存。Windows 用ipconfig /flushdns，Linux 用systemd-resolve --flush-caches，macOS 用sudo dscacheutil -flushcache。清完缓存再打开扩展面板看，很多时候这一步就能解决。

2.3 找到编辑器真正访问的地址

很多时候我们以为编辑器在访问open-vsx.org，但实际上可能被环境变量或已存在的 product.json 改到了别的地址。动手改配置前，先确认真实目标。

VSCodium 的可执行文件在 Linux 下一般叫codium或vscodium。先找到真实安装路径：

which vscodium readlink -f $(which vscodium)

拿到路径后，进入resources/app目录，读product.json：

cat "$(dirname $(readlink -f $(which vscodium)))/resources/app/product.json" | grep -A 8 extensionsGallery

如果输出里有一组extensionsGallery，注意看serviceUrl指向哪里。VSCodium 默认情况下，它的值就是 open-vsx 的地址：

"extensionsGallery": { "serviceUrl": "https://open-vsx.org/vscode/gallery", "itemUrl": "https://open-vsx.org/vscode/item" }

如果指向的是公司内部地址或者某个老镜像，而那个域名已经失效，那问题就找到了。Windows 下如果 VSCodium 装在C:\Program Files\VSCodium\resources\app\product.json，建议先复制出来再改，避免管理员权限弹窗。macOS 则需要去.app包里找。

3. 核心解决思路：换源与改配置

3.1 把数据源切到可用的镜像地址

如果 open-vsx 官方域名在你当前网络环境里很难连上，又不方便从网络层面解决，最简单有效的做法就是换数据源。这个词听起来像大工程，实际就是改一个 URL。

open-vsx 本身是开放项目，不少开源镜像站都会维护一份同步数据。找镜像的方法很简单：在镜像站列表里搜索 open-vsx 关键词，找到支持该项的镜像，然后看它的同步周期和访问速度。不管用哪个镜像，配置格式基本一致。假设镜像根地址是https://mirror.example.com/open-vsx，那么 VSCodium 的配置就是：

"extensionsGallery": { "serviceUrl": "https://mirror.example.com/open-vsx/vscode/gallery", "itemUrl": "https://mirror.example.com/open-vsx/vscode/item" }

为什么这样改就能解决？因为镜像有独立的域名和线路，网络路径不一样。原本卡在 DNS 解析或 TCP 建连的请求，换到另一个域名后，往往能正常完成。这就像小区门口的超市关了，你拐个弯去另一家分店，货还是那些货，只是门脸换了。

选镜像时有两件事值得注意。第一，镜像同步有延迟，刚发布几小时内的扩展在镜像里可能搜不到，这时只能等等，或者手动装 vsix。第二，不同镜像的同步频率和带宽策略不同，高峰期可能比官方还慢。所以选定镜像后，先测一下真实响应：

curl -sS -I --max-time 10 https://mirror.example.com/open-vsx/ curl -sS --max-time 15 -X POST "https://mirror.example.com/open-vsx/vscode/gallery/extensionquery" \ -H "Content-Type: application/json" \ -d '{"filters":[{"criteria":[{"filterType":7,"value":"vscodevim.vim"}]}]}'

两项都过了再写进配置，避免改完依然不能用。

3.2 修改 product.json 的正确姿势

修改 product.json 是 VSCodium 这类桌面发行版最常用的方式。具体 JSON 结构如下，注意要放在最外层，和"name"、"version"这些字段平级：

{ "extensionsGallery": { "serviceUrl": "https://mirror.example.com/open-vsx/vscode/gallery", "itemUrl": "https://mirror.example.com/open-vsx/vscode/item" } }

动手前先备份。Linux 下我习惯用 jq 修改，避免手写 JSON 出错：

sudo cp /usr/share/vscodium/resources/app/product.json /usr/share/vscodium/resources/app/product.json.bak jq '.extensionsGallery = { "serviceUrl": "https://mirror.example.com/open-vsx/vscode/gallery", "itemUrl": "https://mirror.example.com/open-vsx/vscode/item" }' /usr/share/vscodium/resources/app/product.json | sudo tee /usr/share/vscodium/resources/app/product.json > /dev/null

如果你的实际安装路径和示例不同，把两处路径替换掉。要是没有 jq，也可以直接手动编辑文件。保存时注意编码，Windows 下用 UTF-8 不带 BOM。JSON 文件如果解析失败，编辑器可能直接起不来，所以备份文件一定要留好。

Windows 下修改C:\Program Files\VSCodium\resources\app\product.json时会遇到权限问题。我的做法是先把文件复制到用户目录，用 VS Code 改完后再复制回去。如果复制回去时提示需要管理员权限，就在文件资源管理器里手动确认。macOS 在.app包内改完后，通常需要完全退出再从启动台重新打开。

这里特别提醒：VSCodium 程序升级后，安装包可能会把 product.json 覆盖回默认值。今天改好了，下次升级又变回 open-vsx.org。我遇到这个问题后，干脆把修改命令写进了部署脚本，每次升级后自动执行一次，省得反复手动折腾。

3.3 code-server 用户：优先用环境变量而不是改文件

如果你用的不是桌面版 VSCodium，而是 code-server 这类 Web 版，改 product.json 往往不是最优解。code-server 在启动时会读取一组扩展市场环境变量，优先级比默认配置高。在服务进程启动前设置即可：

export VSCODE_GALLERY_SERVICE_URL="https://mirror.example.com/open-vsx/vscode/gallery" export VSCODE_GALLERY_ITEM_URL="https://mirror.example.com/open-vsx/vscode/item"

这些环境变量可以写进 systemd service 的 Environment 字段，也可以写进容器的 Dockerfile。之后重启 code-server，扩展面板请求就会走新地址。比起改 product.json，环境变量方式还有一个额外好处：程序升级不会弄丢这份配置，因为它是独立存在的。

这里有个坑：如果之前已经在环境变量里设置过一个失效地址，那么即使你改了 product.json，环境变量优先级更高，依然会走旧地址。检查时不要漏掉：

env | grep VSCODE_GALLERY

把残留的旧变量清掉再启动。

3.4 更适合团队落地：离线 vsix 与扩展目录预置

在线换源虽然方便，但在完全离线的内网环境里，任何外部域名都不可达，这时候就别再纠结查询接口了。直接跳过市场，在文件系统层面安装扩展。

先在有网络环境的机器上把扩展的 vsix 文件拉下来。open-vsx 的扩展详情页通常有下载 VSIX 的入口，也可以命令行下载：

npx ovsx get vscodevim.vim -o ./ext

拿到.vsix文件后，用命令行安装：

vscodium --install-extension ./ext/vscodevim.vim-1.25.2.vsix --force

图形界面也能装：打开扩展面板，点击右上角...菜单，选择 “Install from VSIX”，然后选中文件。

团队开发环境里更推荐把扩展目录做成共享卷。VS Code 系的扩展默认安装在~/.vscode-oss/extensions或~/.vscodium/extensions，你可以通过--extensions-dir参数改成任意目录：

vscodium --extensions-dir /data/shared/extensions

容器部署时，构建阶段就把 vsix 拷贝进去，启动时执行安装命令：

COPY ./ext /tmp/ext RUN vscodium --install-extension /tmp/ext/ms-python.python.vsix

这样用户在容器里打开编辑器，扩展已经在列表里，全程不依赖市场接口，也不需要等镜像同步。这个方案的工程量比改配置大一点，但一次配好后就不用再操心网络变化，是我在给团队封装开发镜像时最推荐的做法。

3.5 改完配置后如何确认生效

配置改完不能只靠“看起来好了”来验证，最好直接在请求层确认。打开扩展面板，让它自动发一次查询，然后看请求的域名。

桌面版 VSCodium 按Ctrl+Shift+P，执行 “Developer: Toggle Developer Tools”，切到 Network 面板后再触发一次扩展面板刷新。筛选请求地址里的extensionquery，看 Request URL 开头是不是新镜像的域名。

code-server 更简单，浏览器里直接按 F12 打开开发者工具，看同一个请求。

命令行也有笨办法，直接带 verbose 日志启动：

vscodium --verbose 2>&1 | grep -i extensionquery

如果日志里出现open-vsx.org，说明没改对地方，回到 3.2 和 3.3 再确认一遍。如果出现镜像域名，并且响应体里有totalSize字段，说明请求已经通了。

4. 进阶排障与常见问题速查

4.1 改了配置仍报错时，按四个方向查

改完配置还报错的情况也不少见。我第一次从 jq 改完到重启，前后花了不少时间，最后发现改的 product.json 是旧版本程序的，系统里同时装了另一个版本的 VSCodium，运行的却是后者。所以第一个方向是确认“正在运行的程序”用的到底是不是你改的那个文件。

第二个方向是看环境变量。code-server 场景前面已经说过，VSCODE_GALLERY_SERVICE_URL和VSCODE_GALLERY_ITEM_URL优先级很高。检查环境变量有没有残留：

env | grep -i gallery

第三个方向是看系统时间。TLS 握手对系统时间非常敏感，时间不对时任何 HTTPS 站点都连不上，离线机器尤其容易出这种问题。确认时间正常后，再用 curl 的-v参数看握手过程里有没有证书错误。

第四个方向是看安全网关策略。有些网络环境允许 GET 请求，但会掐断带 JSON body 的 POST 请求。表现就是 curl 访问首页正常，但模拟 POST 请求时连接被断开。这种情况下换源也一样会被掐，只能把扩展安装改成离线 vsix 方案。

4.2 不同报错文案意味着什么

同样是扩展市场打不开，事后日志可能长得很不一样。我整理了一份对照表，方便对号入座。

日志关键词	优先怀疑方向	下一步动作
Failed to fetch/TypeError	请求被中断或跨域限制	先 curl 验证通断，再换源
ERR_NAME_NOT_RESOLVED	DNS 解析失败	检查 hosts、换公共 DNS
ERR_CONNECTION_TIMED_OUT	TCP 建连超时	检查链路连通性，换源
ERR_CONNECTION_REFUSED	目标端口主动拒绝	确认服务是否在线、端口是否正确
ERR_CERT_AUTHORITY_INVALID	证书链不被信任	检查证书和系统时间
ERR_CERT_DATE_INVALID	系统时间偏差	同步时间
502 Bad Gateway/503	服务端或镜像异常	等服务恢复或换下一个镜像
404 Not Found	接口路径配置错误	确认 URL 里包含/vscode/gallery

如果日志里同时出现多个关键词，优先解决 DNS，因为 DNS 错了后面全部白搭。这也是我把 hosts 检查放在那么靠前位置的原因。

4.3 快速检索表：场景、现象与首选方案

最后再给一张按场景检索的表，方便你直接抄作业。

使用场景	典型现象	首选方案
VSCodium 桌面版扩展面板空白	日志出现 open-vsx.org Failed to fetch	修改 product.json，配置镜像
code-server 插件市场打不开	查扩展一直转圈	设置 VSCODE_GALLERY 环境变量
完全离线内网，所有外部源不可达	任何市场请求都失败	离线 vsix 安装，共享扩展目录
公司网络只放行部分域名	官方不通，镜像能通	统一配置镜像地址
程序升级后扩展市场再次失效	升级后 product.json 被还原	把配置写进部署脚本

值得多说一句的是，日志里的#1824这种编号真的不用管，换台机器数字就变了。遇到它时，把精力放在 URL 和 err 信息上，问题定位会快很多。

最后说一点个人经验。我曾经对这个报错特别执着，反复重试加上无限换源，后来才明白：处理这类“市场接口连不上”的问题，顺序永远应该是先验证数据源本身能不能访问，再决定是换源还是改配置。现在我给团队的开发容器做镜像时，会提前把镜像地址 curl 一遍，并直接把常用扩展的 vsix 打进镜像里，同事打开编辑器就能用。再分享一个小技巧：程序升级之后如果扩展面板又变回老样子，别先去怀疑网络，先看一眼 product.json 和 VSCODE_GALLERY 环境变量是否被还原，往往问题就出在这里。