国内访问 GitHub 时快时慢，组件下载卡住是常有的事。动手调网络之前，先搞清楚到底是谁在下载：Desktop 下载 QQ 安装包，和服务器拉 Docker 镜像，走的是两套完全不同的网络。这一篇只管 Desktop 自己发起的下载和版本查询；远端那边的问题，见 远端 Linux 和 Docker 部署。
先测一次连接
- 打开「设置 → 网络」。
- 如果你没有专门的代理，就保持「代理模式 → 跟随系统」，GitHub 和 Node.js 的下载线路都保持「自动选择」。
- 滚到「连接测试」，点「测试连接」。
- 看每一项有没有成功、HTTP 返回了什么、响应用了多久。测试用的是你当前填写的草稿，不会改动已经保存的设置。
- 结果没问题的话，点「保存设置」，然后重新发起下载。
代理、下载线路和 GitHub API 分开配置 · 演示数据
保存以后，新发起的下载会用新的配置；已经在下载中的任务，还是沿用它开始时的设置，要等它结束或者停掉以后再重试。
另外，测试结果里的毫秒数是响应耗时，不是下载速度。「自动选择」在真正下载的时候，还会比较各个源的实际吞吐量。所以别只看这里哪个毫秒数最小，就把线路固定死在它上面。
填写代理
先在你的代理软件里找到它的本地 HTTP 或 SOCKS 监听地址。下面例子里的端口只是示范，记得换成你自己的。
- 「代理模式」选「手动配置」。
- 「代理地址」填完整的协议加地址，比如
http://127.0.0.1:7890。 - 代理需要认证的话，分别填「代理用户名（可选）」和「代理密码（可选）」，不要把它们拼到地址里。
- 有局域网服务需要直连的，在「不使用代理的地址」里填主机名、域名、IP 或网段，用英文逗号分开，比如
localhost,192.168.0.0/16。 - 点「测试连接」，哪个字段报错就按提示改。
- 没问题了就「保存设置」，重新发起下载。
| 代理地址 | 域名在哪解析 |
|---|---|
http://127.0.0.1:7890、https://… |
按 HTTP 代理协议处理 |
socks5://127.0.0.1:1080 |
本机解析 |
socks5h://127.0.0.1:1080 |
代理端解析 |
本机回环地址永远不走代理。代理密码存在系统密钥库或者本机的加密存储里，不会写进普通的配置文件，也不会跟着配置 ZIP 一起导出，所以换电脑以后要重新填一次。
三种代理模式
| 选项 | 适用 |
|---|---|
| 跟随系统 | 沿用 Windows 固定代理或代理环境变量；不执行 PAC 脚本 |
| 不使用代理 | Desktop 的外网请求直连，忽略系统代理 |
| 手动配置 | 指定 Desktop 用的 HTTP、HTTPS、SOCKS5 或 SOCKS5H 代理 |
如果浏览器能上网，Desktop 却连不上，看看系统是不是只配了 PAC 自动代理。「跟随系统」不会执行 PAC 脚本，这种情况可以改成手动配置，填代理软件提供的固定地址。
GitHub 和 Node.js 下载线路
这两项是分开设置的。GitHub 线路用于公开的 GitHub 下载，Node.js 线路用于 Node 官方的二进制包。
| 选项 | 行为 |
|---|---|
| 自动选择 | 比较各候选源的实际速度，慢或失败时换别的。配了手动代理时，自动线路走原站，通过代理连接 |
| 仅原站 | 只用官方地址，遵循上面的代理设置，失败不换站 |
| 指定镜像 | 只用选中的内置镜像或自定义地址，失败不换站 |
一般来说，用「自动选择」就够了。如果你确定某个镜像在你的网络环境下一直很稳，再切到「指定镜像」。下载进度里能看到当前用的是哪个源、速度多少、为什么换源。换源会从头重新下载，这是为了避免把不同来源的文件片段拼在一起；快下完的时候，Desktop 会根据剩余时间判断，要不要继续用当前这个源下完。
自定义镜像
- 把对应的「下载线路」设为「指定镜像」。
- 在镜像列表里选「自定义地址」。
- 按下表填写地址，测试通过后保存。
| 类型 | 填什么 | 例子 |
|---|---|---|
| GitHub | 镜像前缀，后面会自动拼上完整的原 URL | https://mirror.example 会拼成 https://mirror.example/https://github.com/owner/repo/...（只是格式示意） |
| Node.js | 包含版本目录的 dist 根地址 | https://registry.npmmirror.com/-/binary/node，版本路径由 Desktop 追加 |
带账号密码、查询参数或签名的链接，以及其他下载站的链接，不会被转发到镜像，还是按代理设置直接访问。
GitHub API 和下载线路的区别
「GitHub API」是用来查版本信息的，「GitHub 下载线路」才是负责下载安装包的。如果你能看到有新版本，但就是下载不动，该查的是下载线路，API 的设置不用动。
- 在「GitHub API → API 访问方式」里选「默认中转，失败后尝试原站」，或者「仅 GitHub 原站」。
- 匿名额度够用的话，「Personal Access Token（可选）」留空就行。
- 想用你自己账号的 API 额度，就填上你的 PAT，测试后保存。
PAT 只会发给 GitHub API，不会发给 API 中转或者下载镜像。它保存在系统密钥库或本机加密存储里，配置包不会带上它。反馈网络问题时，贴错误文字就够了，Token 和密码记得遮掉。
这里管不到的请求
| 请求在哪发生 | 去哪处理 |
|---|---|
| Desktop 下载组件、更新包、查版本 | 本页 |
| 本机 Bot / WebUI | 对应 Bot 或协议端的配置 |
| SSH 连接 | 远端主机档案、网络路径和 SSH 配置 |
Linux 上的 curl、wget、包管理器 |
远端系统的网络配置 |
| 远端 Docker 拉镜像 | 远端 Docker 环境和界面上的镜像源 |
| 框架或插件自己访问 API | 框架或插件自己的代理设置 |
所以，如果 Desktop 这边测试全都通过了，远端任务却还是下载失败，那就去远端任务的日志里看看，是哪个域名、哪条命令出的问题。
按错误排查
- 代理连接被拒绝：代理软件开着吗？协议、IP、端口和它的监听设置一致吗？
- 代理认证失败：检查用户名、密码这两个字段，以及代理那边的认证设置。
- 指定镜像失败：先查地址格式对不对；还是不行的话，换一个镜像，或者改回「自动选择」。
- 测试成功，但下载很慢：看实际下载时的速度和当前用的源。响应快，不代表下大文件也快。
- 保存后，正在下载的任务没变化：当前任务会一直用它开始时的设置，下一次请求才会用上新配置。