主题安装失败主因是网络通道中断，非主题本身问题；常见于直连 marketplace 被 DNS 污染或 TLS 重置、镜像源未同步、安全软件劫持 HTTPS、配置 URL 缺失末尾斜杠等，推荐改用 vscode-cn 镜像源或离线安装并校验版本兼容性。
VSCode 主题插件安装报错，绝大多数不是主题本身有问题，而是 VSCode 无法完成对 marketplace.visualstudio.com 或其镜像源的 HTTPS 请求——本质是网络通道中断，不是文件损坏或兼容性问题。
为什么主题安装总卡在“Installing…”或提示“XHR failed”
主题插件（如 One Dark Pro、Material Theme）和其他扩展一样走同一套安装流程，但因其体积小、无运行时逻辑，失败几乎全由网络层导致。常见现象包括：进度条不动、控制台出现 net::ERR_CONNECTION_RESET、命令面板执行 Extensions: Install from VSIX 后无响应。
- VSCode 默认请求地址是
https://marketplace.visualstudio.com/_apis/public/gallery，国内直连常被 DNS 污染或 TLS 握手重置 - 企业网/校园网可能只放行
open-vsx.org，但部分主题未同步到该源，导致“找不到插件” - 某些安全软件（如腾讯电脑管家、奇安信）会静默劫持 VSCode 的 HTTPS 连接，不弹窗也不报错，只让请求超时
-
extensions.gallery.serviceUrl配置末尾少/（例如写成"https://vscode-cn.com/gallery"而非"https://vscode-cn.com/gallery/"）会导致 404，但 VSCode 不提示具体错误
手动指定 vscode-cn 镜像源最稳（Windows/macOS/Linux 通用）
vscode-cn 是目前更新及时、缓存完整、协议兼容性最好的国内镜像，无需代理，也不依赖系统环境变量。操作只需改两行 JSON，重启即生效。
- 关闭所有 VSCode 窗口，确认后台进程已退出（任务管理器 / 活动监视器里查
Code Helper、Code） - 打开用户设置文件：
%APPDATA%\Code\User\settings.json（Windows）、~/Library/Application Support/Code/User/settings.json（macOS）、~/.config/Code/User/settings.json（Linux） - 添加以下配置（注意逗号位置，确保是合法 JSON）：
"extensions.gallery.serviceUrl": "https://vscode.cdn.azure.cn/_apis/public/gallery/", "extensions.gallery.cacheUrl": "https://vscode.cdn.azure.cn/_apis/public/gallery/publishers"
- 保存后重启 VSCode，再进扩展页搜索主题，首次加载稍慢属正常，但安装成功率显著提升
离线安装主题时 --force 必须配合 code --version 校验
从官网下载的 .vsix 主题包（如 zhuangtongfa.material-theme-3.13.12.vsix）若安装失败，报错 Extension is corrupt 或 Cannot read property 'engines' of undefined，大概率是本地已有同名旧版本残留，或 VSCode 版本低于主题要求。
- 先执行
code --version，记下当前版本（如1.90.2） - 解压
.vsix文件（重命名为.zip即可），打开extension/package.json，检查"engines": {"vscode": "^1.85.0"}这类字段——你当前版本必须 ≥ 1.85.0 且满足范围 - 关掉所有 VSCode 实例，终端执行：
code --install-extension zhuangtongfa.material-theme-3.13.12.vsix --force
- 如果仍失败，说明
.vsix下载不完整：Linux/macOS 执行unzip -t xxx.vsix，Windows PowerShell 执行Expand-Archive xxx.vsix -WhatIf，报错即重下
主题装上了但不生效：别急着重装，先看 Developer: Toggle Developer Tools
安装成功却看不到效果，往往不是主题没装上，而是 VSCode 没激活它，或者扩展主机（extension host）崩溃了。这类问题容易被误判为“安装失败”。
- 按
Ctrl+Shift+P输入Preferences: Color Theme，回车后看列表里有没有你刚装的主题名——有就说明已加载，选中即可生效 - 若列表为空或选中后无变化，打开开发者工具（
Help → Toggle Developer Tools），切到Console标签页，查找Failed to activate extension或Module not found类报错 - 常见真因：
Extension host terminated unexpectedly（某个插件崩溃导致整个扩展系统挂了）、Cannot find module 'vscode'（VSCode 内置 API 版本不匹配）、或主题依赖的字体未安装（如Fira Code主题需额外装字体） - 临时验证：终端执行
code --disable-extensions启动，再手动启用主题插件，排除其他插件干扰
真正难处理的点在于：网络问题和扩展系统崩溃的表现高度相似，但排查路径完全不同。前者看 Network 面板里的请求状态，后者得盯 Console 里的 JS 错误堆栈——很多人卡在这一步，反复重装主题，却没意识到是另一个插件拖垮了整个 host 进程。
