问题背景在本地开发过程中调用某些第三方 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_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 export ALL_PROXYsocks5://127.0.0.1:7890配置完成后再执行curl -v https://api.example.com如果日志中出现Uses proxy env variable HTTPS_PROXY说明当前终端已经默认使用代理配置。如果希望每次打开终端都自动生效可以写入~/.zshrcvim ~/.zshrc追加export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 export ALL_PROXYsocks5://127.0.0.1:7890然后执行source ~/.zshrc后续支持代理环境变量的命令行程序一般就可以自动读取这些配置。Java 场景需要单独关注Java 是这类问题里比较容易踩坑的场景。很多情况下即使终端里已经配置了export HTTPS_PROXYhttp://127.0.0.1:7890Java 程序仍然可能没有使用该代理。原因在于 JVM、HTTP 客户端、IDE 启动方式之间存在差异不同场景下对环境变量的读取行为并不完全一致。比较稳妥的方式是在 JVM 启动参数中显式配置代理java \ -Dhttp.proxyHost127.0.0.1 \ -Dhttp.proxyPort7890 \ -Dhttps.proxyHost127.0.0.1 \ -Dhttps.proxyPort7890 \ -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_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 export ALL_PROXYsocks5://127.0.0.1:78905. 单独确认目标程序是否读取代理配置如果是 Java、Node、Python、CLI 工具或 SDK还需要进一步确认它们是否读取了当前环境变量。必要时可以通过启动参数、配置文件或代码显式指定代理。