代理设置

使用代理设置向导快速生成命令 →

国内访问 GitHub 等海外代码托管平台时，经常会遇到网络超时、克隆极慢或连接被重置（如 Failed to connect to github.com port 443、Connection was reset）等问题。配置本地代理是解决这些网络障碍最有效的方式。

Git 与远程仓库通信主要使用两种协议：HTTPS（形如 https://github.com/...）与 SSH（形如 [email protected]:...）。这两种协议的代理配置完全独立：

• git config 设置的代理仅对 HTTPS 协议生效；
• SSH 协议走系统 OpenSSH 客户端，须在 ~/.ssh/config 中配置代理。

注意

Git 本身不提供代理服务，配置的前提是你本地已经运行了代理客户端（如 Clash、v2rayN、Sing-box 等），并能够提供本地 HTTP 或 SOCKS5 代理端口。

#确认本地代理端口

在配置 Git 之前，请先确认本地代理客户端监听的端口号。常见客户端的默认端口如下：

请根据你的代理客户端实际设置的本地监听地址和端口进行调整，通常本地 IP 为 127.0.0.1。

#HTTPS 协议代理设置

当使用 HTTPS 协议（如 git clone https://github.com/user/repo.git）时，可以通过 git config 命令配置代理。

#推荐方式：仅为 GitHub 设置代理

推荐只为 github.com 配置代理。这样在访问国内或公司内部自建代码平台时，流量仍然保持直连，避免内网仓库访问变慢甚至失败。

# 使用 HTTP 代理（以 7890 端口为例）
git config --global http.https://github.com.proxy http://127.0.0.1:7890

# 或者使用 SOCKS5 代理
git config --global http.https://github.com.proxy socks5://127.0.0.1:7890

提示

这里的配置键名是 http.https://github.com.proxy：

• 开头的 http 代表 Git 内部负责 HTTP/HTTPS 通信的模块名；
• 中间的 https://github.com. 是限定的作用域网址；
• 末尾的 proxy 为配置项。

#设置全局代理

如果你希望所有 HTTP/HTTPS 远程仓库一律通过代理连接：

# 设置全局 HTTP 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 或者使用 SOCKS5 代理
git config --global http.proxy socks5://127.0.0.1:7890
git config --global https.proxy socks5://127.0.0.1:7890

警告

设置全局代理后，所有 Git 操作都会走代理通道。如果代理软件未运行，任何 git clone 或 git fetch 操作都将报错失败；访问国内仓库速度也可能会受到负面影响。

#为单个仓库设置代理

如果你只想在特定项目中使用代理，可以进入该项目的本地目录，去掉 --global 参数即可：

cd my-project
git config http.proxy http://127.0.0.1:7890
git config https.proxy http://127.0.0.1:7890

此配置仅保存在该仓库的 .git/config 文件中，不会影响机器上的其他 Git 仓库。

#取消 HTTPS 代理

当不需要代理，或者代理节点失效想恢复直连时，可以使用 --unset 命令清除：

# 取消仅针对 GitHub 的代理
git config --global --unset http.https://github.com.proxy

# 取消全局代理
git config --global --unset http.proxy
git config --global --unset https.proxy

# 取消当前仓库代理（需在仓库目录下执行）
git config --unset http.proxy
git config --unset https.proxy

#SSH 协议代理设置

当你的仓库地址是 [email protected]:user/repo.git 时，Git 会调用系统自带的 OpenSSH 客户端建立连接。此时通过 git config 配置的代理完全无效。

我们需要在当前用户的 SSH 配置文件 ~/.ssh/config 中为 github.com 配置 ProxyCommand。

• Windows 路径：C:\Users\<你的用户名>\.ssh\config
• macOS / Linux 路径：~/.ssh/config

如果该文件不存在，可以直接手动新建一个（无文件扩展名）。

#Windows 环境配置

Windows 版本的 Git 自带了 connect.exe 代理小工具（位于 Git 安装目录下的 mingw64/bin/ 中，Git Bash 已默认将其加入环境变量）。

在 ~/.ssh/config 文件中追加以下内容：

# 仅对 github.com 生效
Host github.com
    User git
    # 如果使用 HTTP 代理（参数为 -H）
    ProxyCommand connect -H 127.0.0.1:7890 %h %p
    # 如果使用 SOCKS5 代理（参数为 -S）
    # ProxyCommand connect -S 127.0.0.1:7890 %h %p

#macOS 与 Linux 环境配置

macOS 与大多数 Linux 发行版内置了 nc（netcat）工具，可以通过 nc 进行转发。

在 ~/.ssh/config 文件中追加以下内容：

# 仅对 github.com 生效
Host github.com
    User git
    # 如果使用 HTTP 代理
    ProxyCommand nc -X connect -x 127.0.0.1:7890 %h %p
    # 如果使用 SOCKS5 代理（参数为 -X 5）
    # ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p

#突破 22 端口限制（改走 443 端口）

部分公司内网或校园网会屏蔽外部端口 22，导致 SSH 无论如何都连不上。GitHub 官方支持通过 HTTPS 端口（443）走 SSH 协议。

在 ~/.ssh/config 中指定 Hostname ssh.github.com 和 Port 443：

Host github.com
    Hostname ssh.github.com
    Port 443
    User git
    ProxyCommand connect -H 127.0.0.1:7890 %h %p

#测试 SSH 代理连通性

保存配置文件后，在终端中执行测试命令：

ssh -T [email protected]

如果配置成功，终端会返回类似以下的欢迎信息：

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

#终端环境变量代理（临时生效）

如果你只需要在当前命令行窗口临时加速一次克隆，无需修改持久配置文件，可以直接在终端设置环境变量。Git 会自动识别这些变量。

#PowerShell

$env:http_proxy="http://127.0.0.1:7890"
$env:https_proxy="http://127.0.0.1:7890"

# 临时取消
$env:http_proxy=""
$env:https_proxy=""

#Bash / Zsh (macOS / Linux / Git Bash)

export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"

# 临时取消
unset http_proxy
unset https_proxy

#Windows CMD

set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890

# 临时取消
set http_proxy=
set https_proxy=

注意

环境变量仅在当前打开的终端窗口内生效，关闭或新开终端窗口后自动失效。

#查看与排查当前配置

如果不确定当前配置了什么代理，或者怀疑配置被重复覆盖，可以通过以下命令查看：

# 查看针对 GitHub 生效的专有代理
git config --global --get http.https://github.com.proxy

# 查看全局 HTTP 代理
git config --global --get http.proxy

# 查看所有配置项及其所在的配置文件来源
git config --list --show-origin

通过 --show-origin 参数可以清晰地看到每一项配置究竟是来自系统级、全局 ~/.gitconfig 还是当前仓库的 .git/config。

#常见问题与报错排查

#1. 报错：Failed to connect to 127.0.0.1 port xxxx: Connection refused

• 原因：Git 尝试连接本地代理端口，但代理软件未开启，或者代理软件里的监听端口与 Git 配置中的端口不一致。
• 解决办法：
  1. 检查代理客户端是否正常运行；
  2. 确认客户端设置里的本地监听端口（例如是 7890 还是 10808）；
  3. 如果暂时不用代理，请执行上述取消代理的命令。

#2. 报错：OpenSSL SSL_connect: Connection was reset

• 原因：本地直连访问 GitHub 遭到网络阻断，或者配置的代理没有真正生效。
• 解决办法：
  1. 按照上述教程配置专有代理 http.https://github.com.proxy；
  2. 检查使用的克隆地址是否为 HTTPS，如果是 SSH 地址需配置 ~/.ssh/config。

#3. 报错：SSL certificate problem: unable to get local issuer certificate

• 原因：部分代理软件或企业安全网关开启了 HTTPS 流量解密（MITM），Git 无法校验该本地自签名证书。
• 解决办法： 优先将代理客户端设置为纯代理转发，或在代理软件中信任系统根证书。如果是在安全可控的个人开发环境中，可临时关闭 Git 的 SSL 校验：
  复制

  git config --global http.sslVerify false

  警告

  关闭 http.sslVerify 会降低传输安全性，无法防御中间人攻击。问题解决后建议恢复： git config --global http.sslVerify true

#4. 为什么设置了代理，git clone [email protected] 依然超时？

• 原因：地址形如 [email protected]:... 代表使用的是 SSH 协议，而 git config http.proxy 仅仅对 HTTP/HTTPS 协议有效。
• 解决办法：
  • 方案一：改用 HTTPS 方式克隆：git clone https://github.com/user/repo.git；
  • 方案二：按照上文的 SSH 协议代理设置在 ~/.ssh/config 中配置代理。