必须同时配置extensions.gallery.serviceurl和extensions.gallery.cacheurl，二者同域、结尾不带/、写入settings.json，且需彻底退出vscode进程后重启；命令行安装需设vscode_extensions_msa_url环境变量，自动更新还需修改product.json中对应字段。
VSCode 插件市场卡住、安装超时、中文语言包“正在安装”不动——99% 是因为 extensions.gallery.serviceUrl 和 extensions.gallery.cacheUrl 没配对生效，或根本没配。
为什么改了 serviceUrl 还是卡在加载？
VSCode 1.83+ 版本起，只写 extensions.gallery.serviceUrl 不够，必须同时存在 extensions.gallery.cacheUrl，且两者要满足三个硬性条件：
- 同域（比如都用
https://vscode.cdn.azure.cn） - 结尾不能带
/（"https://vscode.cdn.azure.cn/api/gallery"✅，".../api/gallery/"❌） - 必须写在用户级
settings.json（不是工作区设置），否则不加载
常见错误是漏掉 cacheUrl，或者两个 URL 域名不一致（比如一个用 vscode.cdn.azure.cn，另一个误写成 marketplace.visualstudio.com.cn），这种配置会被 VSCode 完全忽略。
怎么验证镜像是否真生效？
别靠“感觉快了”判断，直接看网络请求：
- 按
Ctrl+Shift+P→ 输入并运行Developer: Toggle Developer Tools - 切换到
Console标签页 - 在扩展面板搜索任意插件（如
Python），观察控制台里发出的GET请求
成功时应看到类似：GET https://vscode.cdn.azure.cn/api/gallery/publishers/ms-python/vsextensions/python/。如果仍出现 marketplace.visualstudio.com 或 vscode.blob.core.windows.net，说明配置未加载，或被代理工具劫持。
code --install-extension 命令仍超时怎么办？
命令行安装不读 settings.json，它走的是独立环境变量路径：
- 临时生效：终端里先执行
VSCODE_EXTENSIONS_MSA_URL=https://vscode.cdn.azure.cn code --install-extension esbenp.prettier-vscode - CI/CD 或远程开发中，需在构建脚本里显式导出该变量
- 若仍报
ETIMEDOUT或卡在pending，检查是否后台开着 Clash/Surge 等代理工具——它们常默认启用系统代理但未全局，会干扰code命令的 DNS 解析
某些插件（如 ms-python.python）会额外拉取语言服务器二进制包，这部分完全绕过 gallery 协议，镜像源对其无效，只能离线下载或配 HTTP 代理。
自动更新插件失败？product.json 得动
插件自动更新（比如弹窗提示“有新版本”）不读 settings.json，它硬编码在 VSCode 安装目录下的 product.json 文件里：
- Windows 路径示例：
C:\Users\<username>\AppData\Local\Programs\Microsoft VS Code\resources\app\product.json</username> - macOS 路径示例：
/Applications/Visual Studio Code.app/Contents/Resources/app/product.json - 用文本编辑器打开，搜索
extensionsGallery，把其中的serviceUrl和cacheUrl字段值，全部替换成和settings.json里一致的国内地址
这个文件修改后无需重启 VSCode，但下次检查更新时才会生效。很多人只改了 settings.json 就以为万事大吉，结果更新时又卡住——根源就在这里。
