命令行安装插件（code --install-extension）卡住或超时，根本原因是CLI不读settings.json镜像配置，必须设置VSCODE_EXTENSIONS_MSA_URL环境变量指定镜像源（如https://vscode.cdn.azure.cn），否则默认直连境外marketplace.visualstudio.com导致TLS失败或ETIMEDOUT。
命令行安装插件（code --install-extension）卡住或超时，不是网络差，而是它压根没走你在 settings.json 里配的镜像源——必须靠环境变量兜底，否则永远 fallback 到境外 marketplace。
为什么 code --install-extension 不读 settings.json 镜像配置
VSCode 图形界面启动时会加载用户设置，但命令行工具 code 是独立进程，不自动继承 GUI 的 JSON 配置。哪怕你已正确设置了 extensions.gallery.serviceUrl，code --install-extension 仍默认直连 marketplace.visualstudio.com，国内环境下极易 TLS 握手失败或 ETIMEDOUT。
这不是 bug，是设计如此：CLI 工具需保证可复现、无副作用，不隐式依赖 GUI 状态。
- 验证方式：运行
code --list-extensions --show-versions，若返回空或极慢，基本可断定 CLI 未连上 gallery - 常见错误信息：
ETIMEDOUT、request to https://marketplace.visualstudio.com/... failed、卡在 pending 状态超过 60 秒 - CI/CD 场景（如 GitHub Actions、GitLab Runner）中该问题 100% 复现，因为根本没 GUI 进程
必须设置 VSCODE_EXTENSIONS_MSA_URL 环境变量
这是唯一被 code CLI 官方认可的镜像控制方式，优先级高于 settings.json，且无需重启任何进程。
- 临时生效（当前终端）：
VSCODE_EXTENSIONS_MSA_URL=https://vscode.cdn.azure.cn code --install-extension esbenp.prettier-vscode - 永久生效（Linux/macOS）：在
~/.bashrc或~/.zshrc中追加export VSCODE_EXTENSIONS_MSA_URL="https://vscode.cdn.azure.cn"，然后source ~/.zshrc - Windows PowerShell：运行
$env:VSCODE_EXTENSIONS_MSA_URL="https://vscode.cdn.azure.cn"；如需持久化，用系统属性 → 高级 → 环境变量添加 - 注意：值只需填基础域名（
https://vscode.cdn.azure.cn），不要带/api/gallery路径，CLI 内部会自动拼接
代理冲突比没配镜像更致命
很多用户装了 Clash/Surge/Proxyman，但没设全局模式或规则，导致 code CLI 在后台静默走代理失败——表现为“看起来在动”，实则请求发不出去，日志也不报错。
- 最简排查：运行
curl -I https://vscode.cdn.azure.cn，若返回 200 则镜像可达；若超时或拒绝连接，说明本地网络或代理阻断了该域名 - 强制禁用代理安装：
code --proxy-settings=off --install-extension ms-python.python - 某些语言服务器（如
ms-python.python的 Pylance）会额外从github.com或objects.githubusercontent.com下载二进制，这部分不走VSCODE_EXTENSIONS_MSA_URL，只能离线下载或单独配代理
离线安装 .vsix 是终极保底方案
当环境完全隔离（内网、金融/政企网络）、或某插件在镜像站不同步时，手动下载 .vsix 最可靠。
- 下载地址来源：打开
https://open-vsx.org搜索插件，点 “Download” 获取直链；或从微软 Marketplace 页面右键 “复制链接地址”，把域名换成vscode.cdn.azure.cn后再下载 - 校验完整性：
sha256sum your-extension.vsix对比官网公布的哈希值（部分插件页会提供） - 安装命令：
code --install-extension /path/to/your-extension.vsix，路径必须是绝对路径，相对路径在某些 shell 下会失败 - 杀软拦截高发区：Windows Defender 或 360 常在解压 .vsix 时锁文件，临时关闭“实时保护”再试；避免将 .vsix 放在 OneDrive/iCloud 同步目录
真正容易被忽略的是：命令行和图形界面使用两套完全独立的网络栈，settings.json 对 CLI 无效是常态，不是例外。别花时间清缓存、重装 VSCode、换 DNS——先确认 VSCODE_EXTENSIONS_MSA_URL 是否生效，再查代理是否静默劫持。其他都是障眼法。
