一次本地代理不生效问题的排查复盘
问题背景
在本地开发过程中，调用某些第三方 HTTPS API、CLI 工具或 SDK 时，偶尔会遇到一种比较典型的现象：
浏览器访问正常，本地网络代理工具也已经开启，但终端里的命令行程序仍然请求失败。
常见表现包括：
curl https://api.example.com返回超时、连接失败，或者在 CLI 工具中出现类似错误：
stream disconnected before completionerror sending request for url这类问题表面上看像是“网络不通”，但从排查结果来看，真正的问题通常不是本地代理服务失效，而是：
终端程序没有真正读取代理配置，请求仍然是直连发出的。
一、不要用 ping 判断 HTTPS 代理是否生效
很多人在排查网络问题时，第一反应是执行：
ping api.example.com如果返回：
Request timeout for icmp_seq 0 Request timeout for icmp_seq 1就容易认为目标服务不可访问。
但在代理场景下，ping的参考价值非常有限。
原因在于，ping使用的是 ICMP 协议，而本地常见的代理配置通常是：
HTTP Proxy HTTPS Proxy SOCKS5 Proxy这些代理主要处理 TCP 层上的 HTTP / HTTPS 请求，并不会代理 ICMP 流量。
也就是说，即使本地 HTTP / HTTPS 代理配置完全正常，ping依然可能失败。
因此，在 API 调用场景里，不建议用ping作为主要判断依据。
更合适的方式是使用curl验证 HTTPS 请求链路。
二、用 curl 手动指定代理验证链路
可以先手动指定代理端口进行验证：
curl --proxy http://127.0.0.1:7890 https://api.example.com如果请求可以正常返回，说明本地代理链路本身是可用的。
这个结果至少可以证明：
| 检查项 | 结论 |
|---|---|
| 本地代理端口 | 可连接 |
| 代理服务 | 正常工作 |
| HTTPS 请求 | 可以发出 |
| DNS / TLS / 网络链路 | 基本正常 |
此时问题就不应该继续停留在“网络是不是坏了”这个方向，而应该转向另一个问题：
为什么手动指定代理可以访问，而程序默认访问失败？
答案通常是：
当前终端环境没有配置代理变量，或者目标程序没有读取代理配置。
三、浏览器能访问，不代表终端能访问
这是本地开发环境中最容易误判的地方。
浏览器通常会读取系统代理设置，所以打开系统代理后，Chrome、Safari 等图形界面应用可能可以直接生效。
但终端里的程序不一定会读取系统代理。
常见的终端程序包括：
curl git npm python java node 各种 CLI 工具 各种 SDK这些程序很多时候依赖的是环境变量，而不是系统代理配置。
这说明问题不是代理服务不可用，而是不同程序的请求路径不同。
浏览器请求链路可能是：
浏览器 -> 系统代理 -> 本地代理端口 -> 目标 API 服务而终端程序请求链路可能是：
终端程序 -> 直接访问目标 API 服务如果当前网络环境不支持终端程序直接访问目标地址，请求自然会失败。
四、判断终端是否真正走了代理
可以使用下面的命令查看请求细节：
curl -v https://api.example.com如果当前终端已经读取代理环境变量，日志中通常会看到类似信息：
Uses proxy env variable HTTPS_PROXY == 'http://127.0.0.1:7890'或者看到请求先连接到了本地代理端口：
Connected to 127.0.0.1这说明请求已经先进入本地代理端口，再由代理服务转发。
如果日志中没有任何proxy相关信息，而是直接解析并连接目标域名，则说明当前请求没有走代理。
也可以查看当前终端是否配置了代理环境变量：
env | grep -i proxy如果没有输出，说明当前 shell 环境没有代理配置。
五、给终端配置代理环境变量
如果手动指定代理可以访问：
curl --proxy http://127.0.0.1:7890 https://api.example.com但直接访问失败：
curl https://api.example.com就可以在终端中配置代理环境变量。
临时生效方式：
export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890 export ALL_PROXY=socks5://127.0.0.1:7890配置完成后，再执行：
curl -v https://api.example.com如果日志中出现：
Uses proxy env variable HTTPS_PROXY说明当前终端已经默认使用代理配置。
如果希望每次打开终端都自动生效，可以写入~/.zshrc：
vim ~/.zshrc追加：
export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890 export ALL_PROXY=socks5://127.0.0.1:7890然后执行：
source ~/.zshrc后续支持代理环境变量的命令行程序，一般就可以自动读取这些配置。
Java 场景需要单独关注
Java 是这类问题里比较容易踩坑的场景。
很多情况下，即使终端里已经配置了：
export HTTPS_PROXY=http://127.0.0.1:7890Java 程序仍然可能没有使用该代理。
原因在于 JVM、HTTP 客户端、IDE 启动方式之间存在差异，不同场景下对环境变量的读取行为并不完全一致。
比较稳妥的方式是在 JVM 启动参数中显式配置代理：
java \ -Dhttp.proxyHost=127.0.0.1 \ -Dhttp.proxyPort=7890 \ -Dhttps.proxyHost=127.0.0.1 \ -Dhttps.proxyPort=7890 \ -jar app.jar如果项目使用 OkHttp，也可以在代码里明确指定代理：
Proxy proxy = new Proxy( Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 7890) ); OkHttpClient client = new OkHttpClient.Builder() .proxy(proxy) .build();这种方式比依赖系统环境变量更可控，也更适合本地调试第三方 HTTPS API、模型服务 API 或企业内部网关接口时使用。
推荐排查路径
遇到类似问题，可以按照下面的顺序排查。
1. 验证本地代理端口是否可用
curl --proxy http://127.0.0.1:7890 https://api.example.com如果成功，说明代理链路可用。
2. 验证当前终端是否默认走代理
curl -v https://api.example.com重点观察是否出现：
Uses proxy env variable3. 检查代理环境变量
env | grep -i proxy4. 配置终端代理
export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890 export ALL_PROXY=socks5://127.0.0.1:78905. 单独确认目标程序是否读取代理配置
如果是 Java、Node、Python、CLI 工具或 SDK，还需要进一步确认它们是否读取了当前环境变量。
必要时，可以通过启动参数、配置文件或代码显式指定代理。