国内 macOS 安装 uv 时因网络问题导致下载失败怎么办？

Question

国内 macOS 用户通过 `curl -LsSf https://astral.sh/uv/install.sh | sh` 安装 uv 时，常因 GitHub 域名解析失败、CDN 节点限速或 TLS 连接中断导致下载卡在 `Downloading uv...` 或直接报 `curl: (7) Failed to connect` 错误。根本原因在于安装脚本默认从 `https://github.com/astral-sh/uv/releases/download/` 拉取二进制包，而 GitHub Release 在国内访问不稳定，且 macOS 的 `curl` 默认不走代理（即使系统已配置代理）。此外，部分企业网络会拦截或重置 TLS 握手，加剧失败概率。该问题非 uv 本身缺陷，而是基础设施链路（DNS → CDN → TLS → 代理穿透）在国内环境的典型脆弱性体现，需绕过 GitHub 直连而非简单重试。

Answer 1

```html

一、现象层：典型失败日志与用户侧表征

• curl: (7) Failed to connect to github.com port 443: Connection refused
• Downloading uv... [0%] 卡住超 5 分钟无进展（实测超时阈值常为 300s）
• curl: (35) LibreSSL SSL_connect: Connection reset by peer in connection to github.com:443
• dig github.com +short 返回空或超时 → DNS 污染/劫持证据

二、链路层：国内 macOS 网络栈的四重脆弱性

macOS 的 curl（基于 LibreSSL + Darwin Network Framework）在企业/校园网中面临如下叠加瓶颈：

环节	默认行为	国内异常表现
DNS 解析	使用系统 resolver（/etc/resolv.conf 或 mDNSResponder）	github.com 被污染为不可达 IP 或超时
HTTP(S) 代理穿透	忽略 http_proxy/https_proxy 环境变量（仅部分 curl 版本支持）	即使终端已配置 proxy，curl -L 仍直连 GitHub
TLS 握手	LibreSSL 1.1.1+ 默认启用 TLS 1.3 + ESNI（但服务端不支持）	中间设备重置 TCP 连接（如防火墙深度包检测 DPI）
CDN 路由	GitHub Release 使用 Fastly CDN，国内节点调度策略不透明	返回海外源站 IP（如 140.82.121.x），触发跨境限速

三、验证层：精准定位故障环节的诊断命令集

# 1. DNS 层验证（对比公共 DNS）
dig github.com @223.5.5.5 +short  # 阿里 DNS
dig github.com @8.8.8.8 +short     # Google DNS（若可通）

# 2. TLS 连通性探测（绕过 curl 代理盲区）
openssl s_client -connect github.com:443 -servername github.com -tls1_2

# 3. 代理生效性验证（强制走代理）
HTTPS_PROXY=http://127.0.0.1:7890 curl -v https://github.com/astral-sh/uv/releases

# 4. 安装脚本实际请求路径提取（避免误判）
curl -sSf https://astral.sh/uv/install.sh | grep -o 'https://github.com/[^"]*'

四、解决层：生产环境可用的五级绕行方案

1. 镜像源替代（推荐）：使用清华 TUNA 镜像（同步延迟 < 5min）
   curl -LsSf https://mirrors.tuna.tsinghua.edu.cn/ghproxy/https://raw.githubusercontent.com/astral-sh/uv/main/scripts/install.sh | sh
2. 预下载 + 本地安装：下载 macOS ARM64/x86_64 二进制后离线部署
   curl -L https://ghproxy.com/https://github.com/astral-sh/uv/releases/download/v0.4.32/uv-darwin-aarch64.tar.gz | tar xz
3. curl 强制代理注入：覆盖脚本内硬编码 URL
   HTTPS_PROXY=http://127.0.0.1:7890 curl -LsSf https://astral.sh/uv/install.sh | sed 's|https://github.com|https://ghproxy.com/https://github.com|g' | sh
4. 系统级 curl 配置持久化：echo "proxy = http://127.0.0.1:7890" >> ~/.curlrc
5. 企业网适配方案：禁用 TLS 1.3 + 指定 SNI 域名
   curl --tlsv1.2 --resolve "github.com:443:140.82.121.4" -LsSf ...

五、架构层：构建可持续的国内分发基础设施

根本解法需跳出“单点修复”思维，建立面向开发者的可信分发网络。下图展示推荐的多活冗余架构：

graph LR
  A[用户执行 install.sh] --> B{DNS Resolver}
  B -->|污染/超时| C[ghproxy.com CDN]
  B -->|正常| D[GitHub Fastly]
  C --> E[清华 TUNA 镜像源]
  C --> F[中科大 USTC 镜像源]
  E --> G[自动校验 SHA256 签名]
  F --> G
  G --> H[macOS 二进制安全安装]

六、演进层：从 uv 安装问题看国产化交付范式迁移

• 开源工具链的“最后一公里”交付，正从 全球统一 CDN 向 区域可信镜像 + 自动降级策略 演进
• Rust 工具链（如 cargo、rustup）已内置 CARGO_REGISTRIES_CRATES_IO_PROTOCOL = “sparse” 和镜像协议，uv 可借鉴其 registry 配置模型
• Apple Silicon Mac 的 Rosetta 2 兼容层与签名机制（notarization）加剧了二进制分发复杂度，需在镜像侧完成公证重签名（如使用 codesign --force --deep --sign）
• 未来可推动 uv 官方支持 UV_INSTALL_MIRROR 环境变量，实现零修改兼容国内生态

```